home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
PC World Interactive 7
/
PC World Interactive 7.iso
/
program
/
dosref.EXE
/
CHAPTER.004
< prev
next >
Wrap
Text File
|
1996-01-31
|
228KB
|
4,527 lines
** Programmer's Technical Reference for MSDOS and the IBM PC **
C H A P T E R F O U R
DOS INTERRUPTS AND FUNCTION CALLS
C O N T E N T S
General Programming Guidelines .................................. 4**1
DOS Registers ................................................... 4**2
DOS Stacks ...................................................... 4**3
DOS Interrupts .................................................. 4**4
Interrupt 20h (Terminate) ....................................... 4**5
DOS Services (quick list) ....................................... 4**6
Calling the DOS Services ........................................ 4**7
Version Specific Information .................................... 4**8
Compatibility Problems With DOS 4.0+ ............................ 4**9
PCjr Cartridge Support .......................................... 4**10
eDOS 4.0 ........................................................ 4**11
DOS Services in Detail .......................................... 4**12
General Programming Guidelines .................................. 4**1
Microsoft recommends avoiding the "old style" DOS 1.0 (01h-0Ch and
26h) system calls wherever possible. Programmers are urged to use the
"new style" (DOS 2.0+) handle calls instead.
Do not use "undocumented" functions unless they are critical to your
application and no other reasonable workaround can be found. Remember
that your programs may have to run under various versions of DOS, DOS
clones such as Digital's DR-DOS, the OS/2 Compatibility Box, or Unix
DOS Emulation Window. Such environments or OS simulations do not
always implement the undocumented calls.
DOS 2.x and 3.x lack many of the enhancements found in later
versions. Your application should check the minimum required DOS
version when specific features are required. Do not test for a higher
version than necessary or you will cause problems for machines running
older versions of DOS, such as business machines which are seldom
upgraded, laptops with DOS in ROM, etc.
Direct disk access via hardware or the BIOS should be avoided
unless your program will only be run on specific hardware or under
certain circumstances. Some versions of DOS 2.x treat their disks in
a manner much like 3.x. Some vendors added multiple DOS partitions or
oversize drive support prior to the "official" 3.3 release. Not all
these systems work in the same way! New-type SCSI or ESDI hard disk
controllers do not always emulate all the standard BIOS calls.
DOS Registers ................................................... 4**2
DOS uses the following registers, pointers, and flags when it executes
interrupts and function calls:
┌──────────────────┬────────┬─────────────────────────────────────────┐
│GENERAL REGISTERS │register│ definition │
│ ├────────┼─────────────────────────────────────────┤
│ │ AX │ accumulator (16 bit) │
│ │ AH │ accumulator high-order byte ( 8 bit) │
│ │ AL │ accumulator low order byte ( 8 bit) │
│ │ BX │ base (16 bit) │
│ │ BH │ base high-order byte ( 8 bit) │
│ │ BL │ base low-order byte ( 8 bit) │
│ │ CX │ count (16 bit) │
│ │ CH │ count high order byte ( 8 bit) │
│ │ CL │ count low order byte ( 8 bit) │
│ │ DX │ data (16 bit) │
│ │ DH │ date high order byte ( 8 bit) │
│ │ DL │ data low order byte ( 8 bit) │
├──────────────────┼────────┼─────────────────────────────────────────┤
│SEGMENT REGISTERS │register│ definition │
│ ├────────┼─────────────────────────────────────────┤
│ │ CS │ code segment (16 bit) │
│ │ DS │ data segment (16 bit) │
│ │ SS │ stack segment (16 bit) │
│ │ ES │ extra segment (16 bit) │
├──────────────────┼────────┼─────────────────────────────────────────┤
│INDEX REGISTERS │register│ definition │
│ ├────────┼─────────────────────────────────────────┤
│ │ DI │ destination index (16 bit) │
│ │ SI │ source index (16 bit) │
├──────────────────┼────────┼─────────────────────────────────────────┤
│POINTERS │register│ definition │
│ ├────────┼─────────────────────────────────────────┤
│ │ SP │ stack pointer (16 bit) │
│ │ BP │ base pointer (16 bit) │
│ │ IP │ instruction pointer (16 bit) │
├──────────────────┴────────┴─────────────────────────────────────────┤
│FLAGS AF, CF, DF, IF, OF, PF, SF, TF, ZF │
└─────────────────────────────────────────────────────────────────────┘
These registers, pointers, and flags all work on the "lowest common
denominator" 8088-8086 CPU. DOS makes no attempt to use any of the
special or enhanced instructions available on the later CPUs which will
execute 8088 code, such as the 80186, 80286, 80386, or NEC V20, V30,
V40, or V50.
User registers except AX are preserved unless information is passed
back to the register as indicated in specific function calls.
For PC-MOS/386 on a 386 CPU, the task switching logic saves the
upper half of the 32-bit registers and the complete FS and GS
registers.
The Intel 8088 processors supplied for the early IBM PCs were
defective and did not handle the stack register properly on an INT
instruction. DOS 2.1 added extra logic around interrupt calls for
stack handling; this is the major difference between 2.0 and 2.1.
DOS Stacks ...................................................... 4**3
When DOS takes control after a function call, it switches to an
internal stack. Registers which are not used to return information
(other than AX) are preserved. The calling program's stack must be
large enough to accomodate the interrupt system - at least 128 bytes
in addition to other interrupts.
DOS actually maintains three stacks -
stack 1: 384 bytes (in DOS 3.1)
for functions 00h and for 0Dh and up, and for ints 25h and
26h.
stack 2: 384 bytes (in DOS 3.1)
for function calls 01h through 0Ch.
stack 3: 48 bytes (in DOS 3.1)
for functions 0Dh and above. This stack is the initial stack
used by the int 21h handler before it decides which of the
other two to use. It is also used by function 59h (get
extended error), and 01h to 0Ch if they are called during an
int 24h (critical error) handler. Functions 33h (get/set
break flag), 50h (set process ID), 51h (get process ID) and
62h (get PSP address) do not use any DOS stack under DOS 3.x
(under 2.x, 50h and 51h use stack number 2).
IBM and Microsoft made a change back in DOS 3.0 or 3.1 to reduce the
size of DOS. They reduced the space allocated for scratch areas when
interrupts are being processed. The default seems to vary with the
DOS version and the machine, but 8 stack frames seems to be common.
That means that if you get more than 8 interrupts at the same time,
clock, disk, printer spooler, keyboard, com port, etc., the system will
crash. It usually seems to happen on a network.
DOS 3.2 does some different stack switching than previous versions.
The interrupts which are switched are 02h, 08h, 09h, 0Ah, 0Bh, 0Ch,
0Dh, 0Eh, 70h, 72h, 73h, 74h, 75h, 76h, and 77h. DOS 3.2 has a
special check in the initialization code for a PCjr and don't enable
stack switching on that machine. DOS 3.3 was changed so that no stack
switching occurs on PC, PC-XT, or the PC Portable, and defaults to 9
stacks of 128 bytes in an AT.
Additional stacks can be allocated when DOS loads by using the
STACKS= command in CONFIG.SYS. These stacks are in addition to the
3 internal DOS stacks. STACKS=16,256 means allow 16 interrupts to
interrupt each other and allow 256 bytes for each for scratch area.
DOS Interrupts .................................................. 4**4
Microsoft recommends that a program wishing to examine or set the
contents of any interrupt vector use the DOS function calls 35h and
25h provided for those purposes and avoid referencing the interrupt
vector locations directly.
DOS reserves interrupt numbers 20h to 3Fh for its own use. This
means absolute memory locations 80h to 0FFh are reserved by DOS.
Interrupt 20h - Terminate Current Program ....................... 4**5
(0:0080h)
Issue int 20h to exit from a program. This vector transfers to the
logic in DOS to restore the terminate address, the Ctrl-Break address,
and the critical error exit address to the values they had on entry to
the program. All the file buffers are flushed and all handles are
closed. You should close all files changed in length (see function
calls 10h and 3Eh) before issuing this interrupt. If the changed file
is not closed, its length, time, and date are not recorded correctly
in the directory.
This call is intended for use with .COM programs only.
For a program to pass a completion code or an error code when
terminating, it must use either function call 4Ch (Terminate a
Process) or 31h (Terminate Process and Stay Resident). These two
methods are preferred over using int 20h and the codes returned by
them can be interrogated in batch processing.
Important: Before you issue an interrupt 20h, your program must
ensure that the CS register contains the segment of its
Program Segment Prefix.
Interrupt 20h DOS - Terminate Program
entry no parameters
return The following vectors are restored from the Program Segment
Prefix:
PSP offset interrupt description
0Ah 22h Program Terminate
0Eh 23h Control-C
12h 24h Critical Error
note 1) IBM and Microsoft recommend using int 21h Fn 4Ch. Using int
20h is officially frowned upon since the introduction of DOS
2.0.
2) In DOS 3.2 at least, int 20h merely calls int 21h, fn 00h.
3) Supported by PC-MOS/386.
DOS Services (quick list) ....................................... 4**6
┌────────────────────────────────────────────────────────────────────┐
│Interrupt 21h Function Call Request │
└────────────────────────────────────────────────────────────────────┘
(0:0084h)
DOS provides a wide variety of function calls for character device
I/O, file management, memory management, date and time functions,
execution of other programs, and more. They are grouped as follows:
call description
00h program terminate
01h-0Ch character device I/O, CP/M compatibility format
0Dh-24h file management, CP/M compatibility format
25h-26h nondevice functions, CP/M compatibility format
27h-29h file management, CP/M compatibility format
2Ah-2Eh nondevice functions, CP/M compatibility format
2Fh-38h extended functions
39h-3Bh directory group
3Ch-46h extended file management
47h directory group
48h-4Bh extended memory management
54h-57h extended functions
5Eh-5Fh networking
60h-62h extended functions
63h-66h enhanced foreign language support
List of DOS services: * = undocumented
00h terminate program
01h get keyboard input
02h display character to STDIO
03h get character from STDAUX
04h output character to STDAUX
05h output character to STDPRN
06h direct console I/O - keyboard to screen
07h get char from std I/O without echo
08h get char from std I/O without echo, checks for ^C
09h display a string to STDOUT
0Ah buffered keyboard input
0Bh check STDIN status
0Ch clear keyboard buffer and invoke keyboard function
o 0Dh flush all disk buffers
o 0Eh select disk
0Fh open file with File Control Block
10h close file opened with File Control Block
11h search for first matching file entry
12h search for next matching file entry
13h delete file specified by File Control Block
14h sequential read from file specified by File Control
Block
15h sequential write to file specified by File Control
Block
16h find or create firectory entry for file
17h rename file specified by file control block
18h* unknown
o 19h return current disk drive
o 1Ah set disk transfer area (DTA)
1Bh get current disk drive FAT
1Ch get disk FAT for any drive
1Dh* unknown
1Eh* unknown
1Fh read DOS disk block, default drive
20h* unknown
21h random read from file specified by FCB
22h random write to file specified by FCB
23h return number of records in file specified by FCB
24h set relative file record size field for file specified
by FCB
o 25h set interrupt vector
26h create new Program Segment Prefix (PSP)
27h random file block read from file specified by FCB
28h random file block write to file specified by FCB
29h parse the command line for file name
o 2Ah get the system date
o 2Bh set the system date
o 2Ch get the system time
o 2Dh set the system time
o 2Eh set/clear disk write VERIFY
o 2Fh get the Disk Transfer Address (DTA)
o 30h get DOS version number
31h TSR, files opened remain open
32h read DOS Disk Block
o 33h get or set Ctrl-Break
34h INDOS Critical Section Flag
o 35h get segment and offset address for an interrupt
o 36h get free disk space
37h* get/set option marking character (SWITCHAR)
o 38h return country-dependent information
o 39h create subdirectory
o 3Ah remove subdirectory
o 3Bh change current directory
o 3Ch create and return file handle
o 3Dh open file and return file handle
o 3Eh close file referenced by file handle
o 3Fh read from file referenced by file handle
o 40h write to file referenced by file handle
o 41h delete file
o 42h move file pointer (move read-write pointer for file)
o 43h set/return file attributes
o 44h device IOCTL (I/O control) info
o 45h duplicate file handle
o 46h force a duplicate file handle
o 47h get current directory
o 48h allocate memory
o 49h release allocated memory
o 4Ah modify allocated memory
o 4Bh load or execute a program
o 4Ch terminate prog and return to DOS
o 4Dh get return code of subprocess created by 4Bh
o 4Eh find first matching file
o 4Fh find next matching file
50h* set new current Program Segment Prefix (PSP)
51h* puts current PSP into BX
52h* pointer to the DOS list of lists
53h* translates BPB (Bios Parameter Block, see below)
o 54h get disk verification status (VERIFY)
55h* create PSP: similar to function 26h
o 56h rename a file
o 57h get/set file date and time
58h get/set allocation strategy (DOS 3.x)
o 59h get extended error information
o 5Ah create a unique filename
o 5Bh create a DOS file
o 5Ch lock/unlock file contents
5Dh DOS internal functions
5Eh* network printer
5Fh* network redirection
60h* parse pathname (TRUENAME)
61h* unknown
62h get program segment prefix (PSP)
63h* get lead byte table (DOS 2.25)
64h* unknown
65h get extended country information (DOS 3.3)
66h get/set global code page table (DOS 3.3)
67h set handle count (DOS 3.3)
68h commit file (DOS 3.3)
69h disk serial number (DOS 4.0)
6Ah unknown
6Bh unknown
6Ch extended open/create (DOS 4.0)
Items marked with 'o' are explicitly supported in the OS/2 1.x DOS
Compatibility Box, according to Microsoft. Most everything is
supported in the OS/2 2.0 Virtual DOS Machine, according to IBM.
Calling the DOS Services ........................................ 4**7
The DOS services are invoked by placing the number of the desired
function in register AH, subfunction in AL, setting the other
registers to any specific requirements of the function, and invoking
int 21h.
When the interrupt is called, all register and flag values are
pushed into the stack. Int 21h contains a pointer into an absolute
address in the IBMDOS.COM file. This address is the main loop for the
DOS command handler. The handler pops the register values, compares
them to its list of functions, and executes the function if valid.
When the function is complete, it may pass values back to the command
handler. The handler will push the values into the stack and then
return control to the calling program.
Most functions will return an error code; some return more
information. Details are contained in the listings for the individual
functions. Extended error return codes for most functions may be
obtained by calling function 59h.
Register settings listed are the ones used by DOS. Some functions
will return with garbage values in unused registers. Do not test for
values in unspecified registers; your program may exhibit odd behavior.
DS:DX pointers are the data segment register (DS) indexed to the DH
and DL registers (DX). DX always contains the offset address, DS
contains the segment address.
The File Control Block services (FCB services) were part of DOS 1.0.
Since the release of DOS 2.0, Microsoft has recommended that these
services not be used. A set of considerably more enhanced services
(handle services) were introduced with DOS 2.0. The handle services
provide support for wildcards and subdirectories, and enhanced error
detection via function 59h. The FCB calls also do not support the
sharing modes or file locking functions of the handle calls, making
them unsafe for use with networks or multitaskers.
The data for the following calls was compiled from various Intel,
Microsoft, IBM, and other publications. There are many subtle
differences between MSDOS and PCDOS and between the individual
versions. Differences between the versions are noted as they occur.
There are various ways of calling the DOS functions. For all
methods, the function number is loaded into register AH, subfunctions
and/or parameters are loaded into AL or other registers, and call int
21h by one of the following methods:
A) call interrupt 21h directly (the recommended procedure)
B) perform a long call to offset 50h in the program's PSP.
1) This method will not work under DOS 1.x.
2) Though recommended by Microsoft for DOS 2.0, this method takes
more time and is no longer recommended.
C) place the function number in CL and perform an intrasegment call
to location 05h in the current code segment. This location
contains a long call to the DOS function dispatcher.
1) IBM recommends this method be used only when using existing
programs written for different calling conventions. (such as
converting CP/M programs). This method should be avoided
unless you have some specific use for it.
2) AX is always destroyed by this method.
3) This method is valid only for functions 00h-24h.
D) PC-MOS/386' virtualization scheme results in 200-400+ clocks per
interrupt when run on an 80286 machine since it has to flip in and
out of protected mode at CPU ring 0. TSL recommends the following
procedure for apps that must run quickly on 286 machines:
1) PUSHF
2) CLI
3) CALL DWORD PTR[vector-contents]
This avoids flipping in and out of protected mode and the attendant
overhead. However, TSL specifies this technique should not be used
with native-mode MOS applications.
There are also various ways of exiting from a program. (assuming it
is not intended to be a TSR). All methods except call 4Ch must ensure
that the segment register contains the segment address of the PSP.
A) Interrupt 21h, function 4Ch (Terminate with Result Code). This is
the "official" recommended method of returning to DOS.
B) Interrupt 21h, function 00h (Exit Program). This is the early
style int 21h function call. It simply calls int 20h.
C) Interrupt 20h (Exit).
D) A JMP instruction to offset 00h (int 20h vector) in the Program
Segment Prefix. This is just a roundabout method to call int 20h.
This method was set up in DOS 1.0 for ease of conversion for CP/M
programs. It is no longer recommended for use.
E) A JMP instruction to offset 05h (int 21 vector) in the Program
Segment Prefix, with AH set to 00h or 4Ch. This is another CP/M
type function.
Version Specific Information .................................... 4**8
* Function Calls:
DOS 2.x supports function calls 00h to 57h.
DOS 2.25 is the only version to support function 63h
(foreign keyboard)
DOS 3.x has more sophisticated error handling and detection
function calls available than 2.x.
DOS 3.0 supports function calls 00h to 5Ch and 62h, including
new and changed function calls for version 3.0:
3Dh Open File
59h Get Extended Error
5Ah Create Temporary File
5Bh Create New File
5Ch Lock/Unlock File Access
62h Get Program Segment Prefix Address
DOS 3.1 supports function calls 00h to 62h, including the
new and changed function calls for DOS 3.1:
5E00h Get Machine Name
5E02h Set Printer Setup
5E03h Get Printer Setup
5F02h Get Redirection List Entry
5F03h Redirect Device
5F04h Cancel Redirection
DOS 3.2 supports the following new functions:
44h extended IOCTL functions
DOS 3.3 supports the following new functions:
44h extended IOCTL functions
65h get extended country information (DOS 3.3)
66h get/set global code page table (DOS 3.3)
67h set handle count (DOS 3.3)
68h commit file (DOS 3.3)
DOS 4.0 supports the following new functions:
44h extended IOCTL functions
69h disk serial number
6Ch extended open/create
DOS 5.0 supports the following new int 21h functions:
30h sub 00h Get OEM ID number
sub 01h Get version flag
33h sub 06h Return "real" DOS version number
44h sub 0Dh/68h, Sense Media Type
sub 10h Query IOCTL handle
sub 11h Query IOCTL device
4Bh sub 01h load but don't execute
(formerly undocumented)
sub 05h Enter EXEC State
51h Get Program Segment Prefix
(formerly undocumented)
58h sub 02h Get UMB Link Status
sub 03h Set UMB Link Status
65h Get Extended Country Information
sub 05h Get filename character table
sub 20h Convert character
sub 21h Convert string
sub 22h Convert ASCIIZ string
...and the following other functions:
2Fh sub 1680h MS-DOS Idle Call
Task Switcher API
DOS 6.0 supports the following new int 21h functions:
44h sub 04h adds DoubleSpace flush
PCjr Cartridge Support .......................................... 4**9
==========================
ibm.dos/secrets.2 #1337, from jswitzer, 525 chars, Sat Jul 29 08:48:15 1989
This is a comment to message 1334.
--------------------------
The PCJr ROM cartridges have a command table that lists the name of
each supported command and its vector in the ROM. It does the ROM
match first before the internal command match, actually, so it will
execute what it finds there. Now that I think about it, this means that
you could burn your own ROMs in the proper format and get your own
commands. Neat, I guess.
As to it being in command.com, my DOS 3.3 version has some of the code
about 1A4C. Do a search with debug for "55 AA" and you'll find the
main routine.
Read:comment
Comment to message number 1337. Enter text. End with '.<CR>'
> 55 AA, that's right. That's the ID for a valid ROM. I'll fire up
> symdeb and poke through COMMAND if I can find my little white cane...
==========================
ibm.dos/secrets.2 #1776, from jswitzer, 319 chars, Tue Sep 19 01:33:09 1989
This is a comment to message 1773.
--------------------------
Actually, you can NOP all of the PCJr code without problems -- AST and
Toshiba both have COMMAND.COM without it, and no major problems. The
interesting thing is that PC-DOS 4.0x still has it, and they explicity
say that DOS 4 is NOT supported on the PCJr (*they* meaning IBM, of
course).
What can you figure, huh?
Read:comment
Comment to message number 1776. Enter text. End with '.<CR>'
> I sold my PCjr this morning (I swear to Baud!) and therefore can't make
>a test to see what would happen with 4.0 on the Jr. If IBM still sells
>the PC/JX in Japan that might be the reason for continuing cartridge
>support, since the machine is PCjr-based (well, about the way a PS/2 is
>PC-based).
> I used to run Toshiba DOS 2.11V on the Jr since it was provably faster
>on screen updates and disk access than IBM 2.1 (with a Jr, it doesn't take
>much to make a noticable difference). The only cartridges I had were
>ColorPaint and BASIC, and I can't remember if I used 2.11 with them or
>not.
>
==========================
ibm.dos/secrets.2 #1777, from jswitzer, 251 chars, Tue Sep 19 01:34:24 1989
--------------------------
The PCJr code in COMMAND.COM is ONLY executed on the PCJr and the PCJr
doesn't support normal BIOS expansion ROMs, only the expansion cartridges.
So, no conflict. If you patch out the check for the PCJr machine ID,
though, good luck!
John Switzer
Read:comment
Comment to message number 1777. Enter text. End with '.<CR>'
> Ummm..... lemme go back and look at the listing again. The way it looked
>the first time, it seemed like ALL commands went through the loop.
Compatibility Problems With DOS 4.0 ............................. 4**10
Compatibility problems with DOS 4.00 lie mainly in int 2Ah and int
2Fh. While 2Ah was always reserved, some network software uses this
interrupt. IBM and Microsoft documentation prior to 4.0 strongly
implies that int 2Fh functions not already used by PRINT.COM were open
for general use. DOS 4.00 grabs a number of these functions. The
difference in disk handling when >32mb partitions are used causes
problems with some older software.
Most DOS 4.00 external programs (ASSIGN, SUBST, etc) check for files
being printed - including LABEL. This is part of the enhanced network
support. Almost all DOS 4.00 externals make checks for NETBIOS too.
DOS 5.0 ditched most of this peculiar stuff, making for a much more
stable product.
eDOS 4.0 ........................................................ 4**11
Microsoft had announced their intent to build a multitasking,
multiuser version of MSDOS as early as 1982. As mentioned in Chapter
1, the DOS 4.0 issued to selected OEMS in England and Europe in
'86/'87 is not the same code that was released here as DOS 4.0 in
1988. Microsoft shipped betas of "DOS 4.0" in the US during the same
time period, but the product was never release in the US. The
European DOS 4.0 (eDOS?) is a multitasking DOS written by Microsoft,
while the US DOS 4.0 is a single tasking DOS written by IBM. eDOS 4.0
was released in Europe after 3.1, but before 3.2.
(abstracted from a pre-release document):
`Microsoft Multitasking MS-DOS Product Specification' dated April
28, 1986
MS-DOS 4.0 is a multitasking operating system, developed from and
compatible with MS-DOS 3.1. It supports true multitasking which gives
the user the illusion of and benefits from many independent computers.
Further, MS-DOS 4.0 allows most existing MS-DOS 2.x and 3.x
applications to run without change in the MS-DOS 4.0 multitasking
environment.
(end of abstract).
Gordon Letwin of Microsoft had this to say about eDOS:
(excerpted from "Turning Off The Car To Change Gears" Microsoft Systems
Journal, volume 2, number 2. May 1987)
"DOS 4 was the first product to result from Microsoft's multitasking
DOS effort. We began it even before IBM introduced the PC AT. It was
an ambitious project that was originally to include a protected mode
with mode switching capabilities so it could run on the 8086 or the
286.
A general-purpose multitasking system needs to run in both modes:
the unprotected 8086 mode so that we can run existing DOS
applications, and the protected 286 mode so that we can multitask
arbitrary, unrelated applications. But the architecture of the 286
caused some delays. Although we knew the project would be difficult,
it was only after we'd gotten deeply into it that we realized just how
difficult it would be.
As a result, DOS 4 became too complicated for our schedules.
Because of the pressure of customer demand as well as that of previous
commitments, we broke the project into two parts. DOS 4 runs only in
real mode and provides multitasking only for specialized applications.
DOS 5, which has now been released as OS/2, includes the protected
mode and other features. DOS 4 was delivered in the last half of 1986
and is being sold in special application environments, primarily in
Europe. It is a specialized product that can share the market with
OS/2, because it runs on 8086 hardware, while OS/2 requires a 286.
The move from DOS 4 to OS/2 was a gradual evolutionary process."
(end of excerpt)
eDOS 4.0 consisted of one main program (DOS2/3 compatible) and
several multitasking (background) programs that had to be written
specially. The whole lot was constrained to fit in the single 640k
memory map.
int 21h functions: (some of these appeared in later versions of DOS)
AEXEC Identical to EXEC sub 4.
CREATMEM creates a named area of memory which may be accessed by
other processes. (shared memory \SHAREMEM\...)
CRITENTER, CRITLEAVE (semaphore routines)
CRITERR (This is the one that should have been in DOS 3)
Enables hard error processing or automatically fails hard
errors.
CWAIT Waits for return code from asynchronous process. Returns
when any child process terminates. Children may also be
started as orphans in which case you cannot WAIT for them.
EXEC 4Bh (sub function 4) - Start async process.
FREEZE Stops a specified process running.
GETEXTENDEDERROR - As for DOS3 except it checks version number to
specify the level of error handling - you may ask for a
pointer to the hard error information packet for the latest
hard error.
GETMEM obtains access to a shared memory area previously created.
GETPID Returns process ID and parents process ID.
GET/SET MEMORY PARTITION SIZE
foreground memory is used for ordinary apps. Background
memory is used for DOS 4 apps that don't use the screen (or
only use it through popup functions). Background apps can
also use foreground memory but not vice versa.
KILL Terminates a process.
PBLOCK Block a process until matching PRUN is given. A timeout
is also specified. A memory location is passed which must
be matched in the PRUN. (semaphore)
PIPE Create a pipe. Access it through READ/WRITE/CLOSE (but not
LSEEK).
PRUN Release a blocked process. (semaphore)
RELEASEMEM Release access to shared memory. If the reference count
hits zero then the memory is freed.
RESUME Thaws a frozen process.
SEND SIGNAL
Signals were:
SIGINTR, SIGTERM, SIGPIPE, SIGUSER1, SIGUSER2.
Control C, End of program, Broken pipe, user def,
user def.
Actions were:
Terminate process on receipt, ignore, accept,
sender gets error or acknowledge received signal.
The last one of these returns to the sender immediately -
it is intended for use when processing the signal will take
a long time.
SETFILETABLE (86h) Install a new file handle table. (more than 20
files, as in DOS 3.3+?)
SETPRI Sets process priority (for this process or entire subtree).
SET SIGNAL HANDLER
SLEEP Suspends the current process for given number of
milliseconds. MSC 4.0 had a demo which called 'DOS_sleep'
int 21h/fn 89h - does not appear to be implemented in
known DOS versions.
WAIT As for DOS 3.
int 2Fh functions:
CHECKPU check for popup package installation
POSTPU open/close a popup screen
SAVEPU save popup screen
RESTOREPU restore popup screen
Other useful features:
eDOS 4.0 programs used the Windows .EXE format
programs may share code segments
improved device drivers
the serial port had a full set of IOCTL calls (used through
a new generic IOCTL call).
device drivers could be multi-tasking. They had appropriate
support routines to queue multiple requests (just like OS/2
later provided)
interrupt driven serial ports
sorted disk buffers before writing
The following were listed as possible future enhancements:
File system protection and (not yet available from MS,
permissions though DRI has it)
High performance file system (HPFS was delivered in OS/2 1.2)
Installable file systems (IFS hook is present in US DOS
4.0, deleted in DOS 5 according
to Gordon Letwin of Microsoft)
Symbolic links (they don't have these on OS/2
even now do they?)
Undelete (added with DOS 5.0)
Long names, lowercase names, (OS/2 HPFS, NT NTFS)
access/creation date/time, name
of app creating file, revision
number etc.
According to bits of information picked up from BIX, Wang tested an
alpha version of eDOS 4.0 for use on a laptop project sometime in 1985
but gave up because the OS was unable to cope with "ill behaved"
programs in a reasonable fashion. I talked with one person who had
beta-tested it for MS, who commented "the only thing it would run was
COMMAND.COM." Microsoft has evidently either squashed eDOS completely
or (likely) incorporated it into OS/2. I've been unable to determine
if the French post office still uses eDOS, and to the best I can find
out Apricot Computer never did much with it.
DOSREF user John Dallman contributed the following: (July 1992)
"You put a few notes in DOSREF about the multi-tasking MS-DOS 4.0
that was released in Europe during 1986/87. Notably, you wondered if
it ever reached any customers. I'm sorry to tell you that the answer
is yes - briefly. It was withdrawn owing to serious reliability
problems: Apricot and ICL sold it in the UK, and I've had email from
someone who bought a retail copy in Hong Kong."
Ray Duncan had this to say about eDOS' metamorphosis: (PC Magazine,
October 16, 1990 excerpted from Power Programming, page 464)
"OS/2 as it exists today is a vastly different system than the
protected-mode successor to DOS first envisioned by Microsoft in 1984
and 1985. The earliest version, internally known as DOS 5.0 or
286DOS, was small and relatively fast - it could even be booted from a
floppy disk on a 1mb 80286 machine. The 286DOS application program
interface (API), which was a proper superset of the DOS Int 21h,
Microsoft Mouse Int 33h, and ROM BIOS video Int 10h and keyboard Int
16h interfaces, was small enough to be easily understood and allowed
the straightforward porting of any DOS application. 286DOS was not
burdened with a built-in graphical user interface; the original plan
was to make a protected-mode version of Microsoft Windows available as
a separate product that the user could run on top of 286DOS as an
option.
But somewhere along the torturous path from the original,
experimental implementations of 286DOS to the retail product now known
as OS/2, things went badly awry..."
Microsoft Press' "MSDOS Encyclopedia" shows a reproduction of a late
DOS 1.25 OEM brochure. Microsoft was touting future enhancements to
1.25 including Xenix-compatible pipes, process forks, and
multitasking, as well as "graphics and cursor positioning, kanji
support, multi-user and hard disk support, and networking." Microsoft
certainly thought big, but, alas, the forks, multitasking, and
multiuser support never came about, at least in US versions of DOS.
Oddly, the flyer claims that...
"MS-DOS has no practical limit on disk size. MS-DOS uses 4-byte
XENIX OS compatible pointers for file and disk capacity up to 4
gigabytes."
Umm... yeah. One sort of gets the idea nobody at Microsoft had a
hard disk larger than 32 megabytes...
For the record they actually delivered:
Xenix-compatible pipes DOS 2.0 ("|" operator)
process forks, and multitasking eDOS 4.0 (not delivered in the US)
multi-user never delivered
graphics and cursor positioning DOS 2.0 (ANSI.SYS, more than likely)
kanji support DOS 2.01, 2.25 (double-byte char set)
hard disk support DOS 2.0 (subdirectories)
networking DOS 3.1 (file locking, MS Networks)
Early Microsoft ads pumped DOS' Xenix-like features and promised
Xenix functionality in future releases.
We'll probably never know what the real story was behind eDOS - DOS
4 - DOS 5 - 286DOS - OS/2. Despite Gordon Letwin's acid comments
about problems with the 80286 processor, I doubt the '286 was the
barrier between users and a multitasking MSDOS. I also doubt there
was any shortage of programming talent at Microsoft - Digital
Research's Concurrent DOS and Software Link's PC-MOS were developed
without undue trouble.
Though it's highly unlikely anyone would ever need programming
information for eDOS, I find the entire subject fascinating. IBM had
not only promised the product, they ran ads for it in 1984-85. Who
axed the project? Why? We'll likely never find out.
DOS Services in Detail .......................................... 4**12
INT 21H DOS services
Function (hex)
* Indicates Functions not documented in the IBM DOS Technical
Reference.
Note some functions have been documented in other Microsoft or
licensed OEM documentation.
Function 00h Terminate Program
Ends program, updates, FAT, flushes buffers, restores registers
entry AH 00h
CS segment address of PSP
return none
note 1) Program must place the segment address of the PSP control
block in CS before calling this function.
2) The terminate, ctrl-break,and critical error exit addresses
(0Ah, 0Eh, 12h) are restored to the values they had on entry
to the terminating program, from the values saved in the
program segment prefix at locations PSP:000Ah, PSP:000Eh, and
PSP:0012h.
3) All file buffers are flushed and the handles opened by the
process are closed.
4) Any files that have changed in length and are not closed are
not recorded properly in the directory.
5) Control transfers to the terminate address.
6) This call performs exactly the same function as int 20h.
7) All memory used by the program is returned to DOS. DOS just
goes up the chain of memory blocks and marks any that are
owned by the PSP which is terminating as free.
8) TOS: $00 TERM. Returns system control to the program from
which it started. If EXECed from a program, returns to that
program. If started from DeskTop, returns to DeskTop. This
is important for chaining program segments.
9) Files opened with FCBs are not automatically closed.
10) Supported in PC-MOS/386 compatibility mode, but not available
for native MOS 386-mode applications.
Function 01h Get Keyboard Input
Waits for char at STDIN (if necessary), echoes to STDOUT
entry AH 01h
return AL ASCII character from STDIN (8 bits)
note 1) Checks char for Ctrl-C, if char is Ctrl-C, executes int 23h.
2) For function call 06h, extended ASCII codes require two
function calls. The first call returns 00h as an indicator
that the next call will be an extended ASCII code.
3) Input and output are redirectable. If redirected, there is
no way to detect EOF.
4) TOS: $1 CONIN. Char returns in D0. ASCII code of char in
high byte, keyboard scan code in low byte. Will return
scancode on keys which have no ASCII value.
Function 02h Display Output
Outputs char in DL to STDOUT
entry AH 02h
DL 8 bit data (usually ASCII character)
return none
note 1) If char is 08 (backspace) the cursor is moved 1 char to the
left (nondestructive backspace).
2) If Ctrl-C is detected after input, int 23h is executed.
3) Input and output are redirectable. If redirected, there is no
way to detect disk full.
4) TOS: $2 CONOUT. Char must be placed on the stack as the first
word. The ASCII value of the char goes in the low byte and
the high byte is zero. Chars are output to DEVICE #2, normal
console output. Control characters and escape sequences are
interpreted normally.
5) Under DOS 1.x, 02h sends a character to the active display.
Under DOS 2.x and later, the char goes to STDOUT.
Function 03h Auxiliary Input
Get (or wait until) character from STDAUX
entry AH 03h
return AL ASCII char from auxiliary device
note 1) AUX, COM1, COM2 is unbuffered and not interrupt driven.
2) This function call does not return status or error codes.
For greater control it is recommended that you use the ROM BIOS
routines (int 14h) or write an AUX device driver and use IOCTL.
3) At startup, PC-DOS initializes the first auxiliary port (COM1)
to 2400 baud, no parity, one stop bit, and an 8-bit word.
Versions of MSDOS may differ.
4) If Ctrl-C is has been entered from STDIN, int 23h is executed.
5) TOS: $03 AUXILIARY INPUT. Function returns when the character
has been received. Char is returned in the low byte of D0.
6) Under DOS 1.x, the character is read from COM1. Under DOS
2.x and later, it is read from STDAUX.
Function 04h Auxiliary Output
Write character to STDAUX
entry AH 04h
DL ASCII char to send to AUX
return none
note 1) This function call does not return status or error codes.
For greater control it is recommended that you use the ROM
BIOS routine (int 14h) or write an AUX device driver and use
IOCTL.
2) If Ctrl-C is has been entered from STDIN, int 23h is executed.
3) Default is COM1 unless redirected by DOS.
4) If the device is busy, this function will wait until it is
ready.
5) TOS: $04 AUXILIARY OUTPUT. High byte should be zero, low byte
is ASCII code.
6) Under DOS 1.x, the character is sent to COM1. Under DOS 2.x
and later, it goes to STDAUX.
Function 05h Printer Output
Write character to STDPRN
entry AL 05h
DL ASCII code for character to send
return none
note 1) If Ctrl-C is has been entered from STDIN, int 23h is executed.
2) Default is PRN or LPT1 unless redirected with the MODE command.
3) If the printer is busy, this function will wait until it is
ready.
5) TOS: $05 PRINTER OUTPUT. High byte of D0 is zero, low byte is
character. Returns -1 if character is sent successfully.
Times out after 30 seconds and resets D0 to zero.
6) Under DOS 1.x, this function writes to LPT1. Under DOS 2.x
and higher it writes to STDPRN.
Function 06h Direct Console I/O
Get character from STDIN; echo character to STDOUT
entry AH 06h
DL 0FFh for console input, or 00h-0FEh for console output
return ZF set no character available
clear character recieved
AL ASCII code for character
note 1) Extended ASCII codes require two function calls. The first
call returns 00h to indicate the next call will return an
extended code.
2) If DL is not 0FFh, DL is assumed to have a valid character
that is output to STDOUT.
3) This function does not check for Ctrl-C or Ctrl-PrtSc.
4) Does not echo input to screen.
5) If I/O is redirected, EOF or disk full cannot be detected.
6) TOS: $06 RAWCONIO. Get character from keyboard by calling
with $FF in D0. ASCII and scan codes are returned as per
CONIN. If a value other than $FF is used, it is printed to
STDOUT at the current cursor position. This call interprets
all control chars and escape sequences.
7) Under DOS 1.x, this call handles the keyboard and display
directly. Under DOS 2.x and later, calls are routed to the
STDOUT driver.
Function 07h Direct Console Input Without Echo
Get or wait for char at STDIN, returns char in AL
(does not check BREAK)
entry AH 07h
return AL ASCII character from standard input device
note 1) Extended ASCII codes require two function calls. The first
call returns 00h to indicate the next call will return an
extended code.
2) No checking for Ctrl-C or Ctrl-PrtSc is done.
3) Input is redirectable.
4) TOS: $07 DIRECT CONIN WITHOUT ECHO. Same as function 01h
only does not echo character to screen.
5) Under DOS 1.x the keyboard is read directly. Under DOS 2.x
and later the STDIN is polled.
Function 08h Console Input Without Echo
Get or Wait for char at STDIN, return char in AL
(checks BREAK)
entry AH 08h
return AL char from standard input device
note 1) Char is checked for ctrl-C. If ctrl-C is detected, executes
int 23h.
2) For function call 08h, extended ASCII characters require two
function calls. The first call returns 00h to signify an
extended ASCII code. The next call returns the actual code.
3) Input is redirectable. If redirected, there is no way to
check EOF.
4) TOS: $08 CONIN WITHOUT ECHO. Same as previous call. (no
checking for control characters).
5) Under DOS 1.x the keyboard is read directly. Under DOS 2.x
and later the STDIN is polled.
Function 09h Print String
Outputs Characters in the Print String to the STDOUT
entry AH 09h
DS:DX pointer to the Character String to be displayed
return none
note 1) The character string in memory must be terminated by a $
character. (ASCII 24h)
2) The $ is not displayed but remains in AL forever unless popped.
3) Output to STDOUT is the same as function call 02h.
4) TOS: $09 PRINT LINE. The address of the ASCIIZ string is
placed on the stack as a parameter and is printed at the
current cursor position. There is no limit to the size of the
string. D0 contains the number of characters to be printed.
Control and escape codes are evaluated.
5) Under DOS 1.x, this function writes to the screen. Under DOS
2.x and higher it writes to STDOUT.
Function 0Ah Buffered Keyboard Input
Reads characters from STDIN and places them in the buffer
beginning at the third byte.
entry AH 0Ah
DS:DX pointer to an input buffer
return none
note 1) Min buffer size = 1, max = 255.
2) Char is checked for ctrl-C. If ctrl-C is detected, executes
int 23h.
3) Format of buffer DX:
byte contents
1 Maximum number of chars the buffer will take,
including CR. Reading STDIN and filling the buffer
continues until a carriage return (<Enter> or 0Dh) is
read. If the buffer fills to one less than the maximum
number the buffer can hold, each additional number read
is ignored and ASCII 7 (BEL) is output to the display
until a carriage return is read. (you must set this
value)
2 Actual number of characters received, excluding the
carriage return, which is always the last character.
(the function sets this value)
3-n Characters received are placed into the buffer
starting here. Buffer must be at least as long as the
number in byte 1.
n+1 Carriage return character (0Dh).
4) Input is redirectable. If redirected, there is no way to
check EOF.
5) The string may be edited with the standard DOS editing
commands as it is being entered.
6) Extended ASCII characters are stored as 2 bytes, the first
byte being zero.
7) TOS: $0A READLINE. Fetches CR-terminated line from CONIN.
The address of the buffer is passed as a parameter. Byte 1
is the maximum length of the line, byte 2 is the number of
characters entered, byte 3 is the first character. Escape
codes are not interpreted, but the normal editing control
characters are.
8) Under DOS 1.x the keyboard is read directly. Under DOS 2.x
and later the STDIN is polled.
Function 0Bh Check Standard Input (STDIN) status
Checks for character available at STDIN
entry AH 0Bh
return AL 00h if no character is available from STDIN
0FFh if a character is available from STDIN
note 1) Checks for Ctrl-C. If Ctrl-C is detected, int 23h is executed.
2) Input can be redirected.
3) Checks for character only, it is not read into the application.
4) IBM reports that this call does not work properly under the
DOSSHELL program in DOS 4.00 and 4.01. DOSSHELL will return
all zeroes. This function works correctly from the command
line or application.
5) TOS: $0B CONSTAT. Checks 64-byte OS input buffer.
6) Under DOS 1.x, the type-ahead buffer is checked. Under DOS
2.x and later, the type-ahead buffer is checked unless STDIN
has been redirected.
Function 0Ch Clear Keyboard Buffer & Invoke a Keyboard Function
Dumps buffer, executes function in AL (FCB)
entry AH 0Ch
AL function number (must be 01h, 06h, 07h, 08h, or 0Ah)
note: the DOS 5.0 TR specifies 0Ah as reserved and
"must not be used"
return AL 00h buffer was flushed, no other processing
performed
other any other value has no meaning
note 1) Forces system to wait until a character is typed.
2) Flushes all typeahead input, then executes function specified
by AL (by moving it to AH and repeating the int 21 call).
3) If AL contains a value not in the list above, (such as 00h)
the input buffer is flushed and no other action is taken. Note
that this is the STDIN buffer, not the actual keyboard buffer.
The keyboard buffer will not be flushed if input is redirected.
4) Under DOS 1.x, the type-ahead buffer is emptied before the
function in AL is performed.
Function 0Dh Disk Reset
Flushes all currently open file buffers to disk
entry AH 0Dh
return none
note 1) Does not close files. Does not update directory entries;
files changed in size but not closed are not properly
recorded in the directory.
2) Sets DTA address to DS:0080h
3) Should be used before a disk change, Ctrl-C handlers, and to
flush the buffers to disk.
4) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
5) IBM TopView saves DTA information during task switches.
Function 0Eh Select Disk
Sets the drive specified in DL (if valid) as the default drive
entry AL 0Eh
DL new default drive number (0=A:,1=B:,2=C:,etc.)
return AL number of physical drives found unless LASTDRIVE= is
included in CONFIG.SYS and specifies a higher number
than that of the last physical drive.
note 1) For DOS 1.x and 2.x, the minimum value for AL is 2.
2) For DOS 3.x and 4.x, the minimum value for AL is 5.
3) The drive number returned is not necessarily a valid drive.
4) For DOS 1.x: 16 logical drives are available, A-P. (0-0Fh)
For DOS 2.x: 63 logical drives are available. (Letters are only
used for the first 26 drives. If more than 26
logical drives are used, further drive letters
will be other ASCII characters, such as {, ],
etc. (0-3Fh)
For DOS 3.x, +: 26 logical drives are available, A-Z. (0-19h)
5) TOS: $0E SETDRV. A 16-bit parameter with drivespec is passed
to TOS. On exit, D0 contains the number of the drive active
before the call. (not the total number of drives)
6) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
7) For DOS 3.3, LASTDRIVE= is not needed when accessing
additional hard disk partitions past E:. I haven't done any
further checking, but it seems that LASTDRIVE= may be fairly
useless to most programs.
6) IBM TopView saves DTA information during task switches.
Function 0Fh Open Disk File (FCB)
Searches current directory for specified filename and places
relevantinformation into the File Control Block.
entry AH 0Fh
DS:DX pointer to an unopened FCB
return AL 00h if file found
0FFh if file not not found
note 1) If the drive code was 0 (default drive) it is changed to the
actual drive used (1=A:,2=B:,3=C:, etc). This allows changing
the default drive without interfering with subsequent
operations on this file.
2) The current block field (FCB bytes C-D, offset 0Ch) is set to
zero.
3) The size of the record to be worked with (FCB bytes E-F, offset
0Eh) is set to the system default of 80h. The size of the file
(offset 10h) and the date (offset 14h) are set from information
obtained in the root directory. You can change the default
value for the record size (FCB bytes E-F) or set the random
record size and/or current record field. Perform these actions
after the open but before any disk operations.
4) With DOS 3.x the file is opened in compatibility mode.
(network)
5) Microsoft recommends handle function call 3Dh be used instead.
6) This call is also used by the APPEND command in DOS 3.2 and
higher.
7) Before performing a sequential disk operation on the file, you
must set the Current Record field (offset 20h). Before
performing a random disk operation on the file, you must set
the Relative Record field (offset 21h). If the default record
size of 128 bytes is incorrect, set it to the correct value.
Function 10h Close File (FCB)
Closes a File After a File Write
entry AH 10h
DS:DX pointer to an opened FCB
return AL 00h if the file is found and closed
0FFh if the file is not found in the current
directory
note 1) This function call must be done on open files that are no
longer needed, and after file writes to insure all directory
information is updated.
2) If the file is not found in its correct position in the current
directory, it is assumed that the diskette was changed and AL
returns 0FFh. This error return is reportedly not completely
reliable with DOS version 2.x.
3) If found, the directory is updated to reflect the status in the
FCB, the buffers to that file are flushed, and AL returns 00h.
4) There is a subtle but dangerous quirk to this function. If a
Close request is issued using a File Control Block that has
not been previously activated by a successful Open command, the
file's length will be truncated to zero and the clusters
previously assigned to the file are left floating. (lost
clusters)
5) This function works for files in the current directory only.
6) For DOS 3.1 and later, files opened with this call are set to
compatibility mode and the access code is set to read/write.
7) For DOS 3.0 and later, int 21h fn 59h (Get Extended Error
Information) may be used to determine errors.
Function 11h Search For First Matching Entry (FCB)
Searches current disk & directory for first matching filename
entry AH 11h
DS:DX pointer to address of FCB
return AL 00h successful match
0FFh no matching filename found
note 1) The FCB may contain the wildcard character ? under DOS 2.x,
and ? or * under 3.x and later.
2) The original FCB at DS:DX contains information to continue the
search with function 12h, and should not be modified.
3) If a matching filename is found, AL returns 00h and the
locations at the Disk Transfer Address are set as follows:
a) If the FCB provided for searching was an extended FCB, then
the first byte at the disk transfer address is set to 0FFh
followed by 5 bytes of zeroes, then the attribute byte from
the search FCB, then the drive number used (1=A, 2=B, etc)
then the 32 bytes of the directory entry. Thus, the disk
transfer address contains a valid unopened FCB with the same
search attributes as the search FCB.
b) If the FCB provided for searching was a standard FCB, then
the first byte is set to the drive number used (1=A, 2=b,
etc), and the next 32 bytes contain the matching directory
entry. Thus, the disk transfer address contains a valid
unopened normal FCB.
4) If an extended FCB is used, the following search pattern is
used:
a) If the FCB attribute byte is zero, only normal file entries
are found. Entries for volume label, subdirectories, hidden
or system files, are not returned.
b) If the attribute byte is set for hidden or system files, or
subdirectory entries, it is to be considered as an inclusive
search. All normal file entries plus all entries matching
the specified attributes are returned. To look at all
directory entries except the volume label, the attribute byte
may be set to hidden + system + directory (all 3 bits on).
c) If the attribute field is set for the volume label, it is
considered an exclusive search, and ONLY the volume label
entry is returned.
5) This call is also used by the APPEND command in DOS 3.2+
Function 12h Search For Next Entry Using FCB (FCB)
Search for next matching filename
entry AH 12h
DS:DX pointer to the unopened FCB specified from the previous
Search
First (11h) or Search Next (12h)
return AL 00h if matching filename found
0FFh if matching filename was not found
note 1) After a matching filename has been found using function call
11h, function 12h may be called to find the next match to an
ambiguous request. For DOS 2.x, ?'s are allowed in the
filename. For DOS 3.x and 4.x, global (*) filename characters
are allowed.
2) The DTA contains info from the previous Search First or Search
Next.
3) Do not perform any disk operations with this FCB between a
previous function 11h or 12h call and this one. "Undocumented"
fields in the FCB are used to keep information necessary for
continuing the search, and some disk operations may overwrite
these areas.
4) If the file is found, an FCB is created at the DTA address and
set up to open or delete it.
Function 13h Delete File Via FCB (FCB)
Deletes file specified in FCB from current directory
entry AH 13h
DS:DX pointer to address of FCB
return AL 00h file deleted
0FFh if file not found or was read-only
note 1) All matching current directory entries are deleted. The global
filename character "?" is allowed in the filename.
2) Will not delete files with read-only attribute set.
3) Close open files before deleting them.
4) For DOS 3.1+, requires network Create rights to the sub-
directory.
5) This call supports wildcards and is very fast. The "new"
handle call 41h is supposed to replace this one since it knows
about subdirectories. Unfortunately, fn 41h doesn't know about
wildcards.
Function 14h Sequential Disk File Read (FCB)
Reads record sequentially from disk via FCB
entry AH 14h
DS:DX pointer to an opened FCB
return AL 00h successful read
01h end of file (no data read)
02h Data Transfer Area too small for record size
specified or segment overflow
03h partial record read, EOF found
note 1) The record size is set to the value at offset 0Eh in the FCB.
2) The record pointed to by the Current Block (offset 0Ch) and the
Current Record (offset 20h) fields is loaded at the DTA, then
the Current Block and Current Record fields are incremented.
3) The record is read into memory at the current DTA address as
specified by the most recent call to function 1Ah. If the size
of the record and location of the DTA are such that a segment
overflow or wraparound would occur, the error return is set to
AL=02h.
4) If a partial record is read at the end of the file, it is passed
to the requested size with zeroes and the error return is set to
AL=03h.
5) For DOS 3.1+ networks, requires Read rights to the subdirectory.
Function 15h Sequential Disk Write (FCB)
Writes record specified by FCB sequentially to disk
entry AH 15h
DS:DX pointer to address of FCB
return AL 00h successful write
01h diskette full, write canceled
02h disk transfer area (DTA) too small or segment
wrap
note 1) The data to write is obtained from the disk transfer area.
2) The record size is set to the value at offset 0Eh in the FCB.
3) This service cannot write to files set as read-only.
4) The record pointed to by the Current Block (offset 0Ch) and the
Current Record (offset 20h) fields is loaded at the DTA, then
the Current Block and Current Record fields are incremented.
5) If the record size is less than a sector, the data in the DTA
is written to a buffer; the buffer is written to disk when it
contains a full sector of data, the file is closed, or a Reset
Disk (function 0Dh) is issued.
6) The record is written to disk at the current DTA address as
specified by the most recent call to function 1Ah. If the size
of the record and location of the DTA are such that a segment
overflow or wraparound would occur, the error return is set to
AL=02h.
5) For DOS 3.1+ networks, requires Write rights to the subdirectory.
Function 16h Create A Disk File (FCB)
Search and open or create directory entry for file
entry AH 16h
DS:DX pointer to an FCB
return AL 00h successful creation
0FFh no room in directory
note 1) If a matching directory entry is found, the file is truncated
to zero bytes.
2) If there is no matching filename, a filename is created.
3) This function calls function 0Fh (Open File) after creating or
truncating a file.
4) A hidden file can be created by using an extended FCB with the
attribute byte (offset FCB-1) set to 2.
5) The corresponding handle call is 3Ch.
6) For DOS 3.1+ networks, requires Create rights to the sub-
directory.
7) For DOS 3.0 and later, int 21h function 59h (Get Extended Error
Information) may be used to determine errors.
8) Pathnames and wildcards are not supported.
Function 17h Rename File Specified by File Control Block (FCB)
Renames file in current directory
entry AH 17h
DS:DX pointer to an FCB (see note 4)
return AL 00h successfully renamed
0FFh file not found or filename already exists
note 1) This service cannot rename read-only files.
2) The "?" wildcard may be used.
3) If the "?" wildcard is used in the second filename, the
corresponding letters in the filename of the directory entry are
not changed.
4) A special modified FCB is used. It must have a drive number,
filename, and extension in the usual position, and a second
filename starting 6 bytes after the first, at offset 11h. This
is normally a "reserved" area.
Modified FCB format:
bytes contents
00h drive number
01h-08h old filename (blank padded if required)
09h-0Bh old file extension (blank padded if reqired)
0Ch-10h zeroed out
11h-18h new filename (blank padded if required)
19h-1Bh new file extension (blank padded if required)
1Ch-24h zeroed out
5) The two filenames cannot have the same name.
6) FCB contains new name starting at byte 17h.
7) Under DOS 2.0+, subdirectories may be renamed with this call.
Function 18h Unknown - reportedly not used
entry AH 18h
return AL 00h
Function 19h Get Current Disk Drive
Return designation of current default disk drive
entry AH 19h
return AL current default drive (0=A, 1=B,etc.)
note 1) Some other DOS functions use 0 for default, 1=A, 2=B, etc.
2) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
3) TOS: $19 CURRENT DISK. D0 returns number of drive (0=A:)
Function 1Ah Set Disk Transfer Area Address (DTA)
Sets DTA address to the address specified in DS:DX.
Required for functions 4Eh and 4Fh.
entry AH 1Ah
DS:DX pointer to DTA buffer
return none
note 1) The default DTA is 128 bytes at offset 80h in the PSP. You may
set up your own DTA with any size and location. The DTA should
be large enough to handle the largest record you intend to write.
2) Registers are unchanged.
3) No error codes are returned.
4) Disk transfers cannot wrap around from the end of the segment
to the beginning or overflow into another segment.
5) DOS uses the DTA for file I/O. (see Chapter 6)
6) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
7) TOS: $1A SET DISK TRANSFER ADDRESS. Sets up a 44-byte buffer for
disk operations.
8) PC-MOS/386: not supported for native 386 mode MOS applications.
Function 1Bh Get Current Drive File Allocation Table Information
Returns information from the FAT on the current drive
entry AH 1Bh
return AL number of sectors per allocation unit (cluster)
CX number of bytes per sector
DS:BX address of the current drive's media descriptor byte
DX number of allocation units (clusters) for default drive
note 1) Save DS before calling this function.
2) This call returned a pointer to the FAT in DOS 1.x. Beginning
with DOS 2.00, it returns a pointer only to the table's ID byte.
3) IBM recommends programmers avoid this call and use int 25h
instead.
4) Offset DS:[BX-1] is the dirty byte for the table: 00=clean,
01=dirty.
5) DOS 2.x+ and above do not keep the FAT in RAM. Do not use this
call to access the FAT. Function 36 is preferred.
6) If unsuccessful, AL returns with 0FFh.
Function 1Ch Get File Allocation Table Information for Drive
Returns information on specified drive
entry AH 1Ch
DL drive number (1=A, 2=B, 3=C, etc)
return AL number of sectors per allocation unit (cluster)
0FFh invalid drive specification
DS:BX address of media descriptor byte for drive in DL
CX sector size in bytes
DX number of allocation units (clusters)
note 1) Set DL = 0 for default.
2) Save DS before calling this function.
3) Format of media-descriptor byte:
bits: 0 0 (clear) not double sided
1 (set) double sided
1 0 (clear) not 8 sector
1 (set) 8 sector
2 0 (clear) nonremovable device
1 (set) removable device
3-7 always set (1)
4) This call returned a pointer to the FAT in DOS 1.x. Beginning
with DOS 2.00, it returns a pointer only to the table's ID byte.
5) IBM recommends programmers avoid this call and use int 25h
instead.
6) This function reads the BPB only and is very fast.
7) If unsuccessful, AL returns with 0FFh.
8) PC-MOS/386: native mode should use DS:EBX instead of DS:BX.
Function 1Dh Not Documented by Microsoft
* Unknown - reportedly not used
entry AH 1Dh
return AL 00h
Function 1Eh Not Documented by Microsoft
* Unknown - reportedly not used
entry AH 1Eh
return AL 00h
note Apparently does nothing.
Function 1Fh Get Default Drive Parameter Block
Same as function call 32h (below), except that the table is
accessed from the default drive
entry AH 1Fh
other registers unknown
return AL 00h no error
0FFh error
DS:BX pointer to DOS Disk Parameter Block for default drive.
note For DOS 2, 3, 4.x, this just invokes function 32h (Read DOS
Disk Block) with DL=0.
Function 20h Unknown
* Internal - does nothing?
entry AH 20h
return AL 00h
Function 21h Random Read from File Specified by File Control Block (FCB)
Reads one record as specified in the FCB into the current DTA.
entry AH 21h
DS:DX address of the opened FCB
return AL 00h successful read operation
01h end of file (EOF), no data read
02h DTA too small for the record size specified
03h end of file (EOF), partial data read
note 1) The current block and current record fields are set to agree
with the random record field. Then the record addressed by
these fields is read into memory at the current Disk Transfer
Address.
2) The current file pointers are NOT incremented this function.
3) If the DTA is larger than the file, the file is padded to the
requested length with zeroes.
Function 22h Random Write to File Specified by FCB (FCB)
Writes one record as specified in the FCB to the current DTA
entry AH 22h
DS:DX address of the opened FCB
return AL 00h successful write operation
01h disk full; no data written (write was canceled)
02h DTA too small for the record size specified
(write was canceled)
note 1) This service cannot write to read-only files.
2) The record pointed to by the Current Block (offset 0Ch) and the
Current Record (offset 20h) fields is loaded at the DTA, then
the Current Block and Current Record fields are incremented.
3) If the record size is less than a sector, the data in the DTA is
written to a buffer; the buffer is written to disk when it
contains a full sector of data, the file is closed, or a Reset
Disk (function 0Dh) is issued.
4) The current file pointers are NOT incremented this function.
5) The record is written to disk at the current DTA address as
specified by the most recent call to function 1Ah. If the size
of the record and location of the DTA are such that a segment
overflow or wraparound would occur, the error return is set to
AL=02h.
6) Under networks running DOS 3.1 or later, the user must have
Write access rights to the subdirectory.
Function 23h Get File Size (FCB)
Searches current subdir for matching file, returns size in FCB
entry AH 23h
DS:DX address of an unopened FCB
return AL 00h file found
0FFh file not found
note 1) Record size field (offset 0Eh) must be set before invoking this
function.
2) The disk directory is searched for the matching entry. If a
matching entry is found, the random record field is set to the
number of records in the file. If the value of the Record Size
field is not an even divisor of the file size, the value set in
the relative record field is rounded up. This gives a returned
value larger than the actual file size.
3) This call is used by the APPEND command in DOS 3.2+.
4) Record numbers start with zero.
Function 24h Set Relative Record Field (FCB)
Set random record field specified by an FCB
entry AH 24h
DS:DX address of an opened FCB
return Random Record Field of FCB is set to be same as Current Block
and Current Record.
note 1) You must invoke this function before performing random file
access.
2) The relative record field of FCB (offset 21h) is set to be same
as the Current Block (offset 0Ch) and Current Record (offset
20h).
3) No error codes are returned.
4) The FCB must already be opened.
Function 25h Set Interrupt Vector
entry AH 25h
AL interrupt number to reassign the handler to
DS:DX address of new interrupt vector
return none
note 1) Registers are unchanged.
2) No error codes are returned.
3) The interrupt vector table for the interrupt number specified
in AL is set to the address contained in DS:DX. Use function
35h (Get Vector) to get the contents of the interrupt vector
and save it for later use.
4) When you use function 25 to set an interrupt vector, DOS 3.2
doesn't point the actual interrupt vector to what you requested.
Instead, it sets the interrupt vector to point to a routine
inside DOS, which does this:
1. Save old stack pointer
2. Switch to new stack pointer allocated from DOS's
stack pool
3. Call your routine
4. Restore old stack pointer
The purpose for this was to avoid possible stack overflows when
there are a large number of active interrupts. IBM was
concerned (this was an IBM change, not Microsoft) that on a
Token Ring network there would be a lot of interrupts going on,
and applications that hadn't allocated very much stack space
would get clobbered.
5) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
6) This call is used to access the Phar Lap DOS extender's
protected mode functions. The Phar Lap function number is
placed in AL.
Function 26h Create New Program Segment Prefix (PSP)
This service copies the current program-segment prefix to a new
memory location for the creation of a new program or overlay.
Once the new PSP is in place, a DOS program can read a DOS .COM
or overlay file into the memory location immediately following
the new PSP and pass control to it.
entry AH 26h
DX segment number for the new PSP
return Current PSP is copied to specified segment
note 1) Microsoft recommends you use the newer DOS service 4Bh (EXEC)
instead.
2) The entire 100h area at location 0 in the current PSP is copied
into location 0 of the new PSP. The memory size information at
location 6 in the new segment is updated and the current
termination, ctrl-break, and critical error addresses from the
interrupt vector table entries for ints 22h, 23h, and 24 are
saved in the new program segment starting at 0Ah. They are
restored from this area when the program terminates.
3) The PSP structure is found in Chapter 6.
Function 27h Random Block Read From File Specified by FCB
Similar to 21h (Random Read) except allows multiple files to be
read.
entry AH 27h
CX number of records to be read
DS:DX address of an opened FCB
return AL 00h successful read
01h end of file, no data read
02h DTA too small for record size specified
(read canceled)
03h end of file
CX actual number of records read (includes partial if
AL=03h)
note 1) The record size is specified in the FCB. The service updates
the Current Block (offset 0Ch) and Current Record (offset 20h)
fields to the next record not read.
2) If CX contained 0 on entry, this is a NOP.
3) If the DTA is larger than the file, the file is padded to the
requested length with zeroes.
4) This function assumes that the FCB record size field (0Eh) is
correctly set. If not set by the user, the default is 128
bytes.
5) The record is written to disk at the current DTA address as
specified by the most recent call to function 1Ah. If the size
of the record and location of the DTA are such that a segment
overflow or wraparound would occur, the error return is set to
AL=02h.
6) Under networks running DOS 3.1 or later, the user must have
Read access rights to the subdirectory.
Function 28h Random Block Write to File Specified in FCB
Similar to 27h (Random Write)
entry AH 28h
CX number of records to write
DS:DX address of an opened FCB
return AL 00h successful write
01h disk full, no data written
02h DTA too small for record size specified
(write canceled)
CX number of records written
note 1) The record size is specified in the FCB.
2) This service allocates disk clusters as required.
3) This function assumes that the FCB Record Size field (offset
0Eh) is correctly set. If not set by the user, the default is
128 bytes.
4) The record size is specified in the FCB. The service updates
the Current Block (offset 0Ch) and Current Record (offset 20h)
fields to the next record not read.
5) The record is written to disk at the current DTA address as
specified by the most recent call to function 1Ah. If the size
of the record and location of the DTA are such that a segment
overflow or wraparound would occur, the error return is set to
AL=02h.
6) If called with CX=0, no records are written, but the FCB's File
Size entry (offset 1Ch) is set to the size specified by the
FCB's Relative Record field (offset 21h).
7) Under networks running DOS 3.1 or later, the user must have
Write access rights to the subdirectory.
Function 29h Parse the Command Line for Filename
Parses a text string into the fields of a File Control Block
entry AH 29h
AL bit mask to control parsing
bit 0 0 parsing stops if file seperator found
1 causes service to scan past leading chars
such as blanks. Otherwise assumes the
filename begins in the first byte
1 0 drive number in FCB set to default (0) if
the string contains no drive number
1 drive number in FCB not changed
2 0 filename in FCB set to 8 blanks if no
filename in string
1 filename in FCB not changed if string does
not contain a filename
3 0 extension in FCB set to 3 blanks if no
extension in string
1 extension left unchanged
4-7 must be zero
DS:SI pointer to string to parse
ES:DI pointer to memory buffer to fill with unopened FCB
return AL 00h no wildcards in name or extension
01h wildcards appeared in name or extension
0FFh invalid drive specifier
DS:SI pointer to the first byte after the parsed string
ES:DI pointer to a buffer filled with the unopened FCB
note 1) If the * wildcard characters are found in the command line, this
service will replace all subsequent chars in the FCB with
question marks.
2) This service uses the characters as filename separators
DOS 1 : ; . , + / [ ] = " TAB SPACE
DOS 2,3,4 : ; . , + = TAB SPACE
3) This service uses the characters
: ; . , + < > | / \ [ ] = " TAB SPACE
or any control characters as valid filename separators.
4) A filename cannot contain a filename terminator. If one is
encountered, all processing stops. The handle functions will
allow use of some of these characters.
5) If no valid filename was found on the command line, ES:DI +1
points to a blank (ASCII 32).
6) This call will not handle pathnames.
7) Parsing is in the form D:FILENAME.EXT. If one is found, a
corresponding unopened FCB is built at ES:DI.
Function 2Ah Get Date
Returns day of the week, year, month, and date
entry AH 2Ah
return CX year (1980-2099)
DH month (1-12)
DL day (1-31)
AL weekday 00h Sunday
01h Monday
02h Tuesday
03h Wednesday
04h Thursday
05h Friday
06h Saturday
note 1) Date is adjusted automatically if clock rolls over to the next
day, and takes leap years and number of days in each month into
account.
2) Although DOS cannot set an invalid date, it can read one, such
as 91/32/80, etc.
3) DESQview's DOS subfunctions also accept CX = 4445h and DX =
5351h, i.e. 'DESQ' as valid.
4) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
5) DOS will accept CH=0 (midnight) as a valid time. Through DOS
3.31, if a file's time is set to within 2 seconds of midnight
the time will not be displayed by the DIR command. For DOS
4.0+ and DR-DOS the creation time will always be displayed.
6) TOS: $2A GET DATE.
Function 2Bh Set Date
set current system date
entry AH 2Bh
CX year (1980-2099)
DH month (1-12)
DL day (1-31)
return AL 00h no error (valid date)
0FFh invalid date specified
note 1) On entry, CX:DX must have a valid date in the same format as
returned by function call 2Ah.
2) DOS 3.3+ also sets CMOS clock.
3) Under the DESQview system shell, this is the DV_GET_VERSION
check:
entry AH 2Bh
AL 01h DESQ call
CX 4445h 'DE' (invalid date used
DX 5351h 'SQ' for DesQview ID)
return AH major version
AL minor version
AX 0FFh DESQ not installed (DOS error code)
4) For DESQview 2.00+, installation check
entry AH 2Bh
AL subfunction (DV v2.00+)
01h Get Version
return BX version (BH = major, BL = minor)
note Early copies of v2.00 return 0002h.
02h Get Shadow Buffer Info, and Start
Shadowing
return BH rows in shadow buffer
BL columns in shadow buffer
DX segment of shadow buffer
04h Get Shadow Buffer Info
return BH rows in shadow buffer
BL columns in shadow buffer
DX segment of shadow buffer
05h Stop Shadowing
CX 4445h ('DE')
DX 5351h ('SQ')
return AL 0FFh if DESQview not installed
note In DESQview v1.x, there were no subfunctions; this
call only identified whether or not DESQview was loaded.
5) PC-Tools PC-Cache 5.1 (Multisoft cache) installation check.
entry CX 4358h ('CX')
return AL 00h installed
CX 6378h
0FFh not installed
6) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
7) TOS: GET DATE.
Function 2Ch Get Time
Get current system time from CLOCK$ driver
entry AH 2Ch
return CH hours (0-23)
CL minutes (0-59)
DH seconds (0-59)
DL hundredths of a second (0-99)
note 1) Time is updated every 5/100 second.
2) The date and time are in binary format.
3) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
4) TOS: GET TIME.
Function 2Dh Set Time
Sets current system time
entry AH 2Dh
CH hours (0-23)
CL minutes (0-59)
DH seconds (0-59)
DL hundredths of seconds (0-99)
return AL 00h if no error
0FFh if bad value sent to routine
note 1) DOS 3.3+ also sets CMOS clock.
2) CX and DX must contain a valid time in binary.
3) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
4) TOS: SET TIME.
Function 2Eh Set/Reset Verify Switch
Set verify flag
entry AH 2Eh
AL 00 to turn verify off (default)
01 to turn verify on
DL 00h (DOS 1.x and 2.x only, according to Microsoft's
MS-DOS Encyclopedia. My IBM 2.0 and Intel 2.0
manuals don't show DL being used)
return none
note 1) This is the call invoked by the DOS VERIFY command.
2) The setting of the Verify switch can be obtained by calling
function 54h.
3) This call is not supported on network drives.
4) DOS checks this flag each time it accesses a disk or block
device.
5) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
Function 2Fh Get Disk Transfer Address (DTA)
Returns current DTA used by all DOS read/write operations
entry AH 2Fh
return ES:BX address of DTA
note 1) The DTA is set by function call 1Ah
2) Default DTA address is a 128 byte buffer at offset 80h in that
program's Program Segment Prefix.
3) See Chapter 6 for a description of the DTA.
4) This call is explicitly supported in the OS/2 1.x
Compatibility Box.
5) TOS: GET DTA. Returns segment address of current DTA in D0.
Function 30h Get DOS Version Number
Return DOS version and/or user number
entry AH 30h
(5.0+) AL 00h Get OEM ID number
01h Get version flag
return AH minor version number (i.e., DOS 2.10 returns AX = 0A02h)
(AH undefined for DOS 1.x)
AL major version number (0 for DOS 1.x, 02h for 2.x, 05h
for 5.x)
(DOS 2.0 through 4.01)
BH OEM ID number
00h IBM DOS
16h DEC DOS
0FFh MS-DOS (generic) (Also Toshiba DOS 5.0)
(DOS 5.0+ called with AL=00h)
BH OEM ID number
(see above)
(DOS 5.0+ called with AL=01h)
BH version flag
08h DOS 5.0 or higher running out of ROM
(all other bits are reserved and set to zero)
BL:CX 24-bit user serial number (optional, OEM dependent.
If not used this field returns zeroes)
note 1) If AL returns a major version number of zero, the DOS version
is below 1.28 for MSDOS and below 2.00 for PCDOS.
2) IBM PC-DOS always returns 0000h in BX and CX, as does DR-DOS.
3) Due to OS/2 returning version numbers over 10 and the fact
that some European versions of DOS carried higher version
numbers than IBM's DOS, utilities which check for a DOS version
should not abort if a higher version than required is found
unless some specific problems are known.
4) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
5) TOS: $30 GET VERSION NUMBER. Returns GEMDOS version number
in D0.
6) Under PC-MOS/386, if AX=BX=CX=DX, the PC-MOS/386 version number
is returned. If all registers to not hold the same value, an
MSDOS equivalent version number is returned. The PC-MOS/386
version number is always different from the MSDOS version number.
7) DOS version equivalents:
3.20 PC-MOS/386 v3.0
3.31 Digital Research DR-DOS 3.40, 3.41, 5.0, 6.0
10 OS/2 v1.0 Compatibility Box (major version number)
8) DOS 5.0 adds the AL parameter to the command, but the ID number
returned in BL has been available since MSDOS 2.0, as
documented by Intel's DOS 2.0 Technical Reference.
9) DOS 5.0's SETVER command can modify the value returned in AX.
You must use int 21h/3306h to obtain the true version number.
10) OS/2 1.0's Compatibility Box returns version 10. OS/2 1.1
returns version 10.1, etc. OS/2 2.0 returns version 20.
11) If running in a Microsoft Windows 3.0 or later DOS box, the
string "windir" will be in the DOS environment. Note
lowercase!
12) It may sometimes be necessary to identify DOS-compatible
operating systems or replacement command interpreters. This
doesn't appear to be a simple task.
COMMAND.COM replacements:
1) 4DOS can be identified with int 2Fh, fn 44DDh.
2) Command Plus (unknown)
3) FlexShell (unknown)
DOS replacements:
1) DR-DOS 3.4x has no easy way to be identified, which is a
pity. Though it has some MS4.0-like characteristics, it
reports 3.31 with the DOS call, though VER will return
whatever the DRDOS revision is.
To identify DRDOS I've noted the following:
The string "OS=" appears in the default
environment (unless the user nulls it out)
The OS= string is generated by COMMAND.COM and does not
appear when the user is running 4DOS as a command
interpreter.
The internal DOS version call will report 3.31, but the
string returned by VER is at minimum 3.4.
For DRDOS 3.x:
SHARE and FASTOPEN are always loaded.
For DRDOS 5 and 6:
SHARE and FASTOPEN are NOT always loaded.
The DR-DOS Programmer's Reference doesn't show a call to
identify DR-DOS specifically.
2) PC-MOS/386: unknown. Fail an API call?
3) Concurrent DOS: unknown. Fail an API call?
4) DR Multiuser DOS inserts the string: OS=DRMDOS into the
environment. Since DRMDOS doesn't allow
replacement of the command interpreter via the
SHELL= statement, OS= will be there unless nulled
by the user.
Function 31h Terminate Process and Stay Resident (KEEP)
entry AH 31h
AL exit code
DX program memory requirement in 16 byte paragraphs
return AX return code (retrieveable by function 4Dh)
note 1) Files opened by the application are not closed when this call
is made.
2) Memory can be used more efficiently if the block containing the
copy of the DOS environment is deallocated before terminating.
This can be done by loading ES with the segment contained in 2Ch
of the PSP and issuing function call 49h (Free Allocated Memory).
3) Unlike int 27h, more than 64k may be made resident with this
call.
4) TOS: $31 KEEP PROCESS.
5) Programs larger than 64k may be made resident with this call.
6) For PC-MOS/386, tasks made resident with this call are subject
to being swapped out of memory by the kernel for room to process
other applications. If your code needs to poll the keyboard or
a port, you need to use a device driver instead. PC-MOS does
not swap device drivers.
Function 32h Read DOS Disk Parameter Block
Retrieve the pointer to the drive parameter block for a drive
entry AH 32h
DL drive (0=default, 1=A:, etc.).
return AL 0FFh if drive is not valid or other error
00h if drive is valid and:
DS:BX pointer to DOS Drive Parameter Table. Format of block:
┌────────┬──────┬────────────────────────────────────────
│ Bytes │ Type │ Value
├────────┼──────┼────────────────────────────────────────
│ 00h │ byte │ Drive: 0=A:, 1=B:, etc.
│ 01h │ byte │ Unit within device driver (0, 1, 2, etc.)
│ 02h-03h│ word │ Bytes per sector
│ 04h │ byte │ Sectors per cluster - 1
│ 05h │ byte │ Sectors per cluster as powers of 2
│ 06h-07h│ word │ First sector containing FAT
│ 08h │ byte │ Number of copies of the FAT
│ 09h-0Ah│ word │ Number of root directory entries
│ 0Bh-0Ch│ word │ First sector of first cluster
│ 0Dh-0Eh│ word │ Number of clusters on drive + 1
├────────┴──────┼────────────────────────────────────────
│ DOS 2.x only │
├────────┬──────┼────────────────────────────────────────
│ 0Fh │ byte │ Number of sectors for one copy of the FAT
│ 10h-11h│ word │ Number of first sector of root directory
│ 12h-15h│ dword│ Address of device driver header for this
│ │ │ drive (beginning of device driver)
│ 16h │ byte │ Media Descriptor Byte for this drive
│ 17h │ byte │ 0FFh indicates block must be rebuilt
│ 18h-1Bh│ dword│ address of next DOS Disk Block (0FFFFh
│ │ │ means last in chain)
│ 1Ch │ word │ starting cluster of current dir (0 = root)
│ 1Eh │64byts│ ASCIIZ current directory path string
├────────┴──────┼────────────────────────────────────────
│ DOS 3.x │
├────────┬──────┼────────────────────────────────────────
│ 0Fh │ byte │ number of sectors in one FAT copy
│ 10h │ word │ first sector of root directory
│ 12h │dword │ address of device driver for this drive
│ 16h │ byte │ media descriptor byte for medium
│ 17h │ byte │ 0FFh = block must be rebuilt, 00h
│ │ │ indicates block accessed
│ 18h │dword │ address of next device block, offset
│ │ │ = 0FFFFh indicates last
│ 1Ch │ word │ cluster at which to start search for free
│ │ │ space when writing
│ 1Eh │ word │ number of free clusters on drive, 0FFFFh
│ │ │ unknown?
├────────┴──────┼────────────────────────────────────────
│ DOS 4.0, 5.0 │ (from MS 5.0 TR)
├────────┬──────┼────────────────────────────────────────
│ 0Fh │ word │ number of sectors in one FAT copy
│ 11h │ word │ first sector of containing directory
│ 13h │dword │ address of device driver for this drive
│ 17h │ byte │ media descriptor byte for drive
│ 18h │ byte │ 0FFh = block must be rebuilt, 00h
│ │ │ indicates block accessed
│ 19h │dword │ address of next device block, offset
│ │ │ = 0FFFFh indicates last
│ 1Dh │ word │ last allocated cluster
│ 1Fh │ word │ number of free clusters on drive
└────────┴──────┴────────────────────────────────────────
note 1) Use [BX+0Dh] to find no. of clusters (>1000h, 16-bit FAT; if
not, 12-bit (exact dividing line is probably a little below
1000h to allow for bad sectors, EOF markers, etc.)
2) Short article by C.Petzold, PC Magazine Vol.5, no.8.
3) Some information from the article "Finding Disk Parameters" in
the May 1986 issue of PC Tech Journal.
4) This call is mostly supported in OS/2 1.0's DOS Compatibility
Box. The dword at 12h will not return the address of the next
device driver when in the Compatibility Box.
5) Used by CHKDSK.
Function 33h Control-Break Check
Get or set control-break checking at CON
entry AH 33h
AL 00h see if ^C checking is active
01h to set break checking
DL 00h to disable break checking
01h to enable break checking
02h internal, called by PRINT.COM (DOS 3.1)
03h unknown
04h unknown - DOS 4.0's CPSW command in CONFIG.SYS
calls this function
05h (DOS 4.0+) get boot drive
06h (DOS 5.0+) return "real" DOS version number
instead of number returned by SETVER/int 21h
fn 30h.
return (if AL=00h) break setting
DL 00h if break=off
01h if break=on
(if AL=05h) boot drive
DL 01h A:
02h B: (etc.)
(if AL=06h) real DOS version
BH major version (05h=DOS5)
BL minor version (00h=.00)
DH 0Bh DOS is in ROM
10h DOS is in HMA
DL DOS subversion number (0-7, VER/R reports as A-G)
(all)
AL 0FFh error
note 1) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
2) When ^C checking is on, DOS checks for ^C after each DOS call.
When off, DOS only checks after each DOS character I/O function
from 01h to 0Ch.
Function 34h Return INDOS Flag
Returns ES:BX pointing to Critical Section Flag, byte indicating
whether it is safe to interrupt DOS.
entry AH 34h
return ES:BX points to 1-byte DOS "critical section flag"
note 1) If this byte is 0, it is safe to interrupt DOS.
2) Supported OS/2 1.x Compatibility Box.
3) For PC-MOS/386, this flag indicates whether MOS is using its
stack or a task's stack. If the flag is 0 it is safe to
interrupt MOS.
Function 35h Get Interrupt Vector
Get interrupt vector
entry AH 35h
AL interrupt number (hexadecimal)
return ES:BX address of interrupt vector
note 1) Use function call 25h to set the interrupt vectors.
2) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
Function 36h Get Disk Free Space
get information on specified drive
entry AH 36h
DL drive number (0=default, 1=A:, 2=B:, etc)
return AX number of sectors per cluster
0FFFFh means drive specified in DL is invalid
BX number of available clusters
CX bytes per sector
DX clusters per drive
note 1) Multiply AX * CX * BX for free space on disk.
2) Multiply AX * CX * DX for total disk space.
3) Function 36h returns an incorrect value after an ASSIGN command.
Prior to ASSIGN, the DX register contains 0943h on return, which
is the free space in clusters on the HC diskette. After ASSIGN,
even with no parameters, 0901h is returned in the DX register;
this is an incorrect value. Similar results occur with DD
diskettes on a PC-XT or a PC-AT. This occurs only when the disk
is not the default drive. Results are as expected when the
drive is the default drive. Therefore, the circumvention is to
make the desired drive the default drive prior to issuing this
function call.
4) This function supercedes functions 1Bh and 1Ch.
5) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
6) TOS: $36 GET DISK FREE SPACE.
Function 37h SWITCHAR / AVAILDEV
* Get/set option marking character (is usually "/"), and device type
entry AH 37h
AL 00h read switch character (returns current character
in DL)
01h set character in DL as new switch character
(DOS 2.x) 02h read device availability (as set by function
AL=3) into DL. A 0 means devices that devices
must be accessed in file I/O calls by /dev/device.
A non-zero value means that devices are
accessible at every level of the directory tree
(e.g., PRN is the printer and not a file PRN).
AL=2 to return flag in DL, AL=3 to set from DL
(0 = set, 1 = not set).
(DOS 2.x) 03h get device availability, where:
DL 00h /dev/ must precede device names
01h /dev/ need not precede device
names
return DL switch character (if AL=0 or 1)
device availability flag (if AL=2 or 3)
AL 0FFh the value in AL was not in the range 0-3
note 1) Functions 2 & 3 appear not to be implemented for DOS 3.x.
2) It is documented on page 4.324 of the MS-DOS (version 2)
Programmer's Utility Pack (Microsoft - published by Zenith).
3) Works on all versions of IBM PC-DOS from 2.0 through 3.3.1.
4) The SWITCHAR is the character used for "switches" in DOS command
arguments (defaults to '/', as in "DIR/P"). '-' is popular to
make a system look more like UNIX; if the SWITCHAR is anything
other than '/', then '/' may be used instead of '\' for
pathnames.
5) Ignored by XCOPY, PKARC, LIST, used by PKZIP, LHARC.
6) SWITCHAR may not be set to any character used in a filename.
Legal filename characters vary in DOS 1.x through 6.x.
7) In DOS 3.x you can still read the "AVAILDEV" byte with
subfunction 02h but it always returns 0FFh even if you try to
change it to 0 with subfunction 03h.
8) AVAILDEV=0 means that devices must be referenced in an
imaginary subdirectory "\dev" (similar to UNIX's /dev/*); a
filename "PRN.DAT" can be created on disk and manipulated like
any other. If AVAILDEV != 0 then device names are recognized
anywhere (this is the default): "PRN.DAT" is synonymous with
"PRN:".
9) These functions reportedly are not supported in the same
fashion in various implementations of DOS.
10) Used in DOS 3.3 by CHKDSK, BASIC, and DEBUG.
11) SWITCHAR is not supported in the OS/2 1.x Compatibility Box.
12) Not supported by the aftermarket 4DOS command interpreter in
versions prior to 3.0.
13) The MSDOS Encyclopedia reports: "XENIX used a forward slash as
a separator, but versions 1.x of MS-DOS, borrowing from the
tradition of DEC operating systems, already used the forward
slash for switches on the command line, so Microsoft, at IBM's
request, decided to use the backslash as the separator instead."
14) SWITCHAR is not supported in MS-DOS 5.0.
Function 38h Return Country-Dependent Information
(PCDOS 2.0, 2.1, MSDOS 2.00 only)
entry AH 38h
AL function code (must be 0 in DOS 2.x)
DS:DX pointer to 32 byte memory buffer for returned information
return CF set on error
AX error code (02h)
BX country code
DS:DX pointer to buffer filled with country information:
bytes 00h,01h date/time format
0000h USA standard H:M:S M-D-Y
0001h European standard H:M:S D/M/Y
0002h Japanese standard H:M:S D:M:Y
02h ASCIIZ string currency symbol
03h byte of zeroes
04h ASCIIZ string thousands separator
05h byte of zeroes
06h ASCIIZ string decimal separator
07h byte of zeroes
24 bytes 08h-1Fh reserved
Function 38h Get Country-Dependent Information
(PCDOS 3.x+, MSDOS 2.01+)
entry AH 38h
AL function code
00h to get current country information
01h-0FEh country code to get information for, for
countries with codes less than 255
0FFh to get country information for countries with
a code greater than 255
BX 16 bit country code if AL=0FFh
DS:DX pointer to the memory buffer where the data will be
returned
DX 0FFFFh if setting country code rather than getting info
return CF 0 (clear) function completed
1 (set) error
AX error code
02h invalid country code (no table
for it)
(if DX <> 0FFFFh)
BX country code (usually international telephone code)
DS:DX pointer to country data buffer
bytes 0,1 date/time format
0 USA standard H:M:S M/D/Y
1 European standard H:M:S D/M/Y
2 Japanese standard H:M:S D:M:Y
bytes 02h-06h ASCIIZ currency symbol
byte 07h ASCIIZ thousands separator
byte 08h byte of zeroes
byte 09h ASCIIZ decimal separator
byte 0Ah byte of zeroes
byte 0Bh ASCIIZ date separator
byte 0Ch byte of zeroes
byte 0Dh ASCIIZ time separator
byte 0Eh byte of zeroes
byte 0Fh currency format byte
bit 0 0 if currency symbol precedes the value
1 if currency symbol is after the value
1 0 no spaces between value and currency
symbol
1 one space between value and currency
symbol
2 1 if currency symbol replaces decimal
point
3-7 not defined by Microsoft
byte 10h number of significant decimal digits in currency
(number of places to right of decimal point)
byte 11h time format byte
bit 0 0 12 hour clock
1 24 hour clock
1-7 unknown, probably not used
bytes 12h-15h address of case map routine (FAR CALL, AL=char
to map)
entry AL ASCII code of character to be
converted to uppercase
return AL ASCII code of the uppercase input
character
byte 16h data-list separator character
byte 17h zeroes
bytes 18h-21h 5 words reserved
note 1) When an alternate keyboard handler is invoked, the keyboard
routine is loaded into user memory starting at the lowest
portion of available user memory. The BIOS interrupt vector
that services the keyboard is redirected to the memory area
where the new routine resides. Each new routine takes up about
1.6K of memory and has lookup tables that return values unique
to each language. (KEYBxx in the DOS book)
Once the keyboard interrupt vector is changed by the DOS
keyboard routine, the new routine services all calls unless the
system is returned to the US format by the ctrl-alt-F1 keystroke
combination. This does not change the interrupt vector back to
the BIOS location; it merely passes the table lookup to the ROM
locations.
2) Ctrl-Alt-F1 will only change systems with US ROMS to the US
layout. Some systems are delivered with non-US keyboard
handler routines in ROM. (Amstrad machines)
3) Case mapping call: the segment/offset of a FAR procedure that
performs country-specific lower-to-upper case mapping on ASCII
characters 80h to 0FFh. It is called with the character to be
mapped in AL. If there is an uppercase code for the letter, it
is returned in AL, if there is no code or the function was
called with a value of less than 80h AL is returned unchanged.
4) This call is fully implemented in MS-DOS version 2.01 and
higher. It is in version 2.00 but not fully implemented
(according to Microsoft).
5) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
6) For PC-MOS/386 native mode apps, use DS:EDX instead of DS:DX.
Function 38h Set Country Dependent Information
entry AH 38h
AL code country code to set information for, for
countries with codes less than 255
0FFh to set country information for countries with
a code greater than 255
BX 16 bit country code if AL=0FFh
DX 0FFFFh
return CF clear successful
set if error
AX error code (02h)
note 1) Some country codes are:
061 Australia ("International English" in DOS 5.0)
032 Belgium
055 Brazil (DOS 5.0)
002 French-Canadian
042 Czechoslovakia (DOS 5.0)
045 Denmark
358 Finland
033 France
049 Germany
036 Hungary (DOS 5.0)
972 Israel
039 Italy
081 Japan
758 Middle East
031 Netherlands
047 Norway
048 Poland (DOS 5.0)
351 Portugal
003 Latin America
034 Spain
046 Sweden
041 Switzerland
088 Taiwan (MS 4.0+, but not DRDOS 5 or 6)
044 U.K.
001 USA
038 Yugoslavia (DOS 5.0)
2) The country code is the same as the 3-digit international
telephone code for that country.
3) The documentation for COUNTRY= will tell you which codes are
valid for your particular DOS version. Different OEM
implementations of the same DOS version may not support the
same countries.
4) TSL offers support for developing special country code drivers
for PC-MOS/386. Version 4.10 comes with:
061 Australia
032 Belgium
002 French-Canadian
045 Denmark
358 Finland
033 France
049 Germany
972 Israel
039 Italy
758 Middle East
031 Netherlands
047 Norway
351 Portugal
034 Spain
046 Sweden
041 Switzerland
044 U.K.
001 USA
5) For PC-MOS/386 native mode apps, use DS:EDX instead of DS:DX.
Function 39h Create Subdirectory (MKDIR)
Makes a subdirectory along the indicated path
entry AH 39h
DS:DX address of ASCIIZ directory pathname string
return flag CF 0 successful
1 error
AX error code if any (03h, 05h)
(DOS 5.0) (02h, 03h, 05h)
note 1) The ASCIIZ string contains the drive and subdirectory.
2) Drive may be any valid drive (not necessarily current drive).
3) The pathname cannot exceed 64 characters. (same with
PC-MOS/386)
4) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
5) The characters [, ] , =, and " may not be used in subdirectory
names.
6) TOS: $39 MKDIR.
7) For DOS 3.1+ networks, the user must have Create access to the
subdirectory.
8) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 3Ah Remove Subdirectory (RMDIR)
entry AH 3Ah
DS:DX address of ASCIIZ pathname string
return CF clear successful
set AX error code if any (03h, 05h, 10h)
note 1) The ASCIIZ string contains the drive and subdirectory.
2) Drive may be any valid drive (not necessarily current drive).
3) The pathname cannot exceed 64 characters.
4) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
5) TOS: $3A RMDIR.
7) For DOS 3.1+ networks, the user must have Delete access to the
subdirectory.
8) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 3Bh Change Current Directory (CHDIR)
entry AH 3Bh
DS:DX address of ASCIIZ string
return flag CF 0 successful
1 error
AX error code if any (03h)
note 1) The pathname cannot exceed 64 characters including separators.
2) The ASCIIZ string may contain drive and subdirectory.
3) Drive may be any valid drive (not necessarily current drive).
This call will not change the current logged drive.
4) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
5) TOS: $3B CHDIR.
6) The pathspec may not contain wildcards.
7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 3Ch Create A File (CREAT)
Create a file with handle
entry AH 3Ch
CX byte, attributes for file
00h normal read/write
01h read only
02h hidden
04h system
08h volume label
20h archive bit
DS:DX address of ASCIIZ filename string
return CF 0 successful creation
1 error
AX 16 bit file handle
or error code (03h, 04h, 05h)
note 1) The ASCIIZ string may contain drive and subdirectory.
2) Drive may be any valid drive (not necessarily current drive).
3) If the volume label or subdirectory bits are set in CX, they are
ignored.
4) The file is opened in read/write mode
5) If the file does not exist, it is created. If one of the same
name exists, it is truncated to a length of 0.
6) Good practice is to attempt to open a file with fn 3Dh and jump
to an error routine if successful, create file if 3Dh fails.
That way an existing file will not be truncated and overwritten.
7) If the application will run only on DOS 3.x or higher, fn 5Bh
should be used as it automatically creates the file if it does
not exist, preventing problems with networks or multitaskers.
8) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
9) TOS: $3C CREAT.
10) For DOS 3.1+ networks, the user must have Create access to the
subdirectory.
11) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 3Dh Open A File
Open disk file with handle
entry AH 3Dh
AL access code byte
(DOS 2.x) bits 0-2 file attribute
000 read only
001 write only
010 read/write (default)
3-7 reserved, should be set to zero
(DOS 3.x) bits 0-2 file attribute
000 read only
001 write only
010 read/write (default)
3 reserved, should be set to zero
4-6 sharing mode (network)
000 compatibility mode (default)
001 read/write access denied (exclusive)
010 write access denied
011 read access denied
100 full access permitted
7 inheritance flag
0 file inherited by child process
1 file private to child process
DS:DX address of ASCIIZ drive/path/filename string
return CF set on error
AX error code - MS-DOS (01h, 02h, 03h, 04h, 05h,
0Ch)
- DR-DOS (02h, 04h, 05h, 0Ch) and
MS-DOS 5.0
AX 16 bit DOS file handle
note 1) Opens any normal, system, or hidden file.
2) Files that end in a colon are not opened.
3) The read/write pointer is set at the first byte of the file and
the record size of the file is 1 byte (the read/write pointer
can be changed through function call 42h). The returned file
handle must be used for all subsequent input and output to the
file.
4) If the file handle was inherited from a parent process or was
duplicated by DUP or FORCEDUP, all sharing and access
restrictions are also inherited.
5) A file sharing error (error 01h) causes an int 24h to execute
with an error code of 02h.
6) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
7) TOS: $3D OPEN.
8) If any process opens a file that denies a level of access, all
subsequent requests to open the file at that level of access
will fail.
9) Any attempt to open a file with a sharing mode that is already
breached by an existing process will always fail.
10) Used by APPEND in DOS 3.2,+.
11) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 3Eh Close A File Handle
Close a file and release handle for reuse
entry AH 3Eh
BX file handle (generated by 3Dh)
return flag CF clear successful close
set error
AX error code if error (06h)
note 1) When executed, the file is closed, the directory is updated,
and all buffers for that file are flushed. If the file was
changed, the time and date stamps are changed to reflect the
current time.
2) If called with the handle 00000h, it will close STDIN (normally
the keyboard).
3) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
4) TOS: $3E CLOSE.
5) In most versions of DOS only 15 file handles are available for
user processes. It is good practice to close a file handle
when you are not using it.
6) For DOS 3.1+ networks, all file locks must be removed before
the file is closed. Closing a file with active locks is
unpredictable.
7) Although closing a file invalidates the corresponding handle,
DOS may reuse the handle to identify a file that is subsequently
opened or created. You can use int 21h/440Ah (Is File or Device
Remote) to tell if a given handle is valid.
Function 3Fh Read From A File Or Device
Read from file with handle
entry AH 3Fh
BX file handle
CX number of bytes to read
DS:DX address of buffer
return flag CF clear successful read
set error
AX 00h pointer was already at end of file
or number of bytes read
or error code (05h, 06h)
note 1) This function attempts to transfer the number of bytes specified
in CX to a buffer location. It is not guaranteed that all bytes
will be read.
2) If performed from STDIN (file handle 0000), the input can be
redirected.
3) If used to read the keyboard, it will only read to the first CR.
4) The file pointer is incremented to the last byte read.
5) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
6) TOS: $3F READ.
7) If AX < CX a partial record was read.
8) For DOS 3.1+ networks, the user must have Read access to the
subdirectory.
11) For PC-MOS/386 native mode, use DS:EDX and ECX instead of DS:DX
and CX.
Function 40h Write To A File Or Device
Write to file with handle
entry AH 40h
BX file handle
CX number of bytes to write
DS:DX address of buffer
return CF clear successful write
set error
AX number of bytes written
or error code (05h, 06h)
note 1) This call attempts to transfer the number of bytes indicated
in CX from a buffer to a file. If CX and AX do not match after
the write, an error has taken place; however no error code will
be returned for this problem. This is usually caused by a full
disk.
2) If the write is performed to STDOUT (handle 0001), it may be
redirected.
3) To truncate the file at the current position of the file
pointer, set the number of bytes in CX to zero before calling
int 21h. The pointer can be moved to any desired position with
function 42h.
4) This function will not write to a file or device marked
read-only.
5) May also be used to display strings to CON instead of fn 09h.
This function will write CX bytes and stop; fn 09h will
continue to write until a '$' character is found.
6) This is the call that DOS actually uses to write to the screen
in DOS 2.x and above.
7) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
8) TOS: $40 WRITE.
9) For PC-MOS/386 native mode, use DS:EDX and ECX instead of DS:DX
and CX.
Function 41h Delete A File From A Specified Subdirectory (UNLINK)
entry AH 41h
DS:DX pointer to ASCIIZ filespec to delete
return CF clear successful
set error
AX error code if any (02h, 05h)
note 1) This function will not work on a file marked read-only.
2) Wildcards are not accepted.
3) For deleting multiple files, function 13h is faster.
4) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
5) TOS: $41 UNLINK.
6) For DOS 3.1+ networks, the user must have Delete access to the
subdirectory.
7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 42h Move a File Read/Write Pointer (LSEEK)
entry AH 42h
AL method code byte
00h offset from beginning of file
01h offset from present location
02h offset from end of file
BX file handle
CX:DX offset into file (high/low word) in bytes
return AX:DX new file pointer (segment/offset)
CF set error
AX error code (01h, 06h)
clear successful move
note 1) If pointer is at end of file, reflects file size in bytes.
2) The value in DX:AX is the absolute 32 bit byte offset from the
beginning of the file.
3) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
4) TOS: $42 LSEEK.
5) File most be open.
6) For PC-MOS/386 native mode, use ECX instead of CX.
Function 43h Get/Set file attributes (CHMOD)
entry AH 43h
AL 00h get file attributes
01h set file attributes
CX file attributes to set
bit 0 read only
1 hidden file
2 system file
3 volume label
4 subdirectory
5 written since backup (archive bit)
6,7 not used
8 shareable (Novell NetWare)
9-F not used
DS:DX segment/offset pointer to full ASCIIZ file name
return CF set if error
AX error code - MSDOS (01h, 02h, 03h, 05h)
DRDOS (02h, 03h, 05h)
CX file attributes on get
attributes:
00h normal
01h read only
02h hidden
04h system
08h volume label
10h file is subdirectory
20h archive
note 1) This call will not change the volume label or directory bits.
2) Any combination of file attributes may be used.
3) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
4) TOS: $43 CHANGE MODE (CHMOD).
5) For DOS 3.1+ networks, the user must have Create access to the
subdirectory.
6) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 44h I/O Control for Devices (IOCTL)
provided with full version of DOSREF
Function 45h Duplicate a File Handle (DUP)
entry AH 45h
BX file handle to duplicate
return CF clear AX duplicate handle
set AX error code (04h, 06h)
note 1) If you move the pointer of one handle with 3Fh (Read), 40h
(Write), or 42h (Move Pointer) the pointer of the other will
also be moved.
2) The handle in BX must be open.
3) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
4) TOS: $45 DUP.
5) This call can be used to update the directory entry of a file
without the overhead of opening and closing it. For example,
this call followed by fn 3Eh (Close File) with the duplicate
file handle will cause DOS to flush its buffers and update the
directory entry while the original file remains open in read/
write mode.
Function 46h Force Duplicate of a Handle (FORCEDUP or CDUP)
Forces handle in CX to refer to the same file at the
same position as BX
entry AH 46h
BX existing open file handle to duplicate
CX new file handle
return CF clear both handles now refer to existing file
set error
AX error code (04h, 06h)
note 1) If CX was an open file, it is closed first.
2) If you move the pointer of one handle with 3Fh (Read), 40h
(Write), or 42h (Move Pointer) the pointer of the other will
also be moved.
3) The handle in BX must be open.
4) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
5) TOS $46 FORCE.
6) This call may be used for redirecting input and output.
Function 47h Get Current Directory
Places full pathname of current directory/drive into
a buffer
entry AH 47h
DL drive (0=default, 1=A:, etc.)
DS:SI segment/offset pointer to 64-byte buffer area
return CF clear DS:DI pointer to ASCIIZ pathname of the current
directory
set AX error code (0Fh)
note 1) String does not begin with a drive identifier or a backslash.
2) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
3) TOS: $47 GETDIR.
4) For PC-MOS/386 native mode, use DS:ESI instead of DS:SI.
Function 48h Allocate Memory (MALLOC)
Allocates the requested number of 16-byte paragraphs
of memory
entry AH 48h
BX number of 16-byte paragraphs desired
return CF clear AX segment address of allocated space
BX maximum number paragraphs available
set AX error code (07h, 08h)
note 1) BX indicates maximum memory available only if allocation fails.
2) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
3) TOS: $48 MALLOC.
4) Native-mode PC-MOS/386 applications allocate memory via MOS'
interrupt 0D4h API function 11h.
5) When in TopView this call is checked to ensure none of the
addresses are outside the application's memory partition.
Function 49h Free Allocated Memory
Frees specified memory blocks
entry AH 49h
ES segment address of area to be freed
return CF clear successful
set AX error code (07h, 09h)
note 1) This call is only valid when freeing memory obtained by
function 48h.
2) A program should not try to release memory not belonging to it.
3) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
4) TOS: $49 MFREE.
5) Native-mode PC-MOS/386 applications allocate memory via MOS'
interrupt 0D4h API function 12h.
6) When in TopView this call is checked to ensure none of the
addresses are outside the application's memory partition.
Function 4Ah Modify Allocated Memory Blocks (SETBLOCK)
Expand or shrink memory for a program
entry AH 4Ah
BX new size in 16 byte paragraphs
ES segment address of block to change
return CF clear nothing
set AX error code (07h, 08h, 09h)
or BX maximum number of paragraphs available
note 1) Max number paragraphs available is returned only if the call
fails.
2) Memory can be expanded only if there is memory available.
3) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
4) TOS: $4A SETBLOCK.
5) Native-mode PC-MOS/386 applications allocate memory via MOS'
interrupt 0D4h API function 12h.
6) When in TopView this call is checked to ensure none of the
addresses are outside the application's memory partition.
Function 4Bh Load or Execute a Program (EXEC)
entry AH 4Bh
AL 00h load and execute program. A PSP is built for
the program the ctrl-break and terminate
addresses are set to the new PSP.
(DOS 5.0) *01h load but don't execute (internal, DOS 3.x &
DESQview) (see note 1)
*02h load but do not execute (internal,
DOS 2.x only)
03h load overlay (do not create PSP, do not begin
execution)
*04h start async process (Euro-DOS 4.0 only)
(see note 12)
(DOS 5.0) 05h EnterExecState API (see note 17)
DS:DX segment/offset pointer to the ASCIIZ string with the
drive, path, and filename to be loaded
ES:BX segment/offset pointer to a parameter block for the load
(AL=00h) word segment address of environment string
to be passed (0=use current)
dword pointer to the command line to be
placed at PSP+80h
dword pointer to default FCB to be passed at
PSP+5Ch
dword pointer to default FCB to be passed at
PSP+6Ch
(*AL=01h) word segment of environment (0 = use current)
dword pointer to command line
dword pointer to FCB 1
dword pointer to FCB 2
(DOS 3.x+) dword will hold SS:SP on return
(DOS 3.x+) dword will hold program entry point (CS:IP) on
return
(*AL=02h) word segment of environment (0 = use current)
dword pointer to command line
dword pointer to FCB 1
dword pointer to FCB 2
(AL=03h) word segment address where file will be
loaded
word relocation factor to be applied to the
image
return CF set error
AX error code (01h - 05h, 08h, 0Ah, 0Bh)
CF clear if successful
for fn 00h, process ID set to new program's PSP; get
with function 62h
for fn 01h and DOS 3.x+ or DESQview, process ID set
to new program's PSP; get with function 62h
for fn 01h and DOS 2.x, new program's initial stack
and entry point returned in registers
for fn 02h, new program's initial stack and entry point
are returned in the registers
note 1) If you make this call with AL=1 the program will be loaded as
if you made the call with AL=0 except that the program will not
be executed. Additionally, with AL=1 the stack segment and
pointer along with the program's CS:IP entry point are returned
to the program which made the 4B01h call. These values are put
in the four words at ES:BX+0Eh. On entry to the call ES:BX
points to the environment address, the command line and the
two default FCBs. This form of EXEC is used by DEBUG.COM.
2) Application programs may invoke a secondary copy of the command
processor (normally COMMAND.COM) by using the EXEC function.
Your program may pass a DOS command as a parameter that the
secondary command processor will execute as though it had been
entered from the standard input device.
The procedure is:
A. Assure that adequate free memory (17k for 2.x and 3.0, 23k
for 3.1) exists to contain the second copy of the command
processor and the command it is to execute. This is
accomplished by executing function call 4Ah to shrink memory
allocated to that of your current requirements. Next,
execute function call 48h with BX=0FFFFh. This returns the
amount of memory available.
B. Build a parameter string for the secondary command processor
in the form:
1 byte length of parameter string
xx bytes parameter string
1 byte 0Dh (carriage return)
For example, the assembly language statement below would
build the string to cause execution of the command FOO.EXE:
DB 19,"/C C:FOO",13
C. Use the EXEC function call (4Bh), function value 0 to cause
execution of the secondary copy of the command processor.
(The drive, directory, and name of the command processor can
be obtained from the COMSPEC variable in the DOS environment
passed to you at PSP+2Ch.)
D. Remember to set offset 2 of the EXEC control block to point
to the string built above.
3) All open files of a process are duplicated in the newly created
process after an EXEC, except for files originally opened with
the inheritance bit set to 1.
4) The environment is a copy of the original command processor's
environment. Changes to the EXECed environment are not passed
back to the original. The environment is followed by a copy of
the DS:DX filename passed to the child process. A zero value
will cause the child process to inherit the environment of the
calling process. The segment address of the environment is
placed at offset 2Ch of the PSP of the program being invoked.
5) This function uses the same resident part of COMMAND.COM, but
makes a duplicate of the transient part.
6) How EXEC knows where to return to: Basically the vector for int
22h holds the Terminate address for the current process. When
a process gets started, the previous contents of int 22h get
tucked away in the PSP for that process, then int 22h gets
modified. So if Process A EXECs process B, while Process B is
running, the vector for int 22h holds the address to return to
in Process A, while the save location in Process B's PSP holds
the address that process A will return to when *it* terminates.
When Process B terminates by one of the usual legal means, the
contents of int 22h are (surmising) shoved onto the stack, the
old terminate vector contents are copied back to int 22h vector
from Process B's PSP, then a RETF or equivalent is executed to
return control to process A.
7) To load an overlay file with 4B: first, don't de-allocate the
memory that the overlay will load into. With the other 4Bh
functions, the opposite is true - you have to free the memory
first, with function 4Ah. Second, the "segment address where
the file will be loaded" (first item in the parameter block for
sub-function 03) should be a paragraph boundary within your
currently-allocated memory. Third, if the procedures within
the overlay are FAR procs (while they execute, CS will be
equal to the segment address of the overlay area), the
relocation factor should be set to zero. On the other hand,
if the CS register will be different from the overlay area's
segment address, the relocation factor should be set to
represent the difference. You determine where in memory the
overlay file will load by using the segment address mentioned
above. Overlay files are .EXEs (containing header, relocation
table, and memory image).
8) When function 00h returns, all registers are changed,
including the stack. You must resore SS, SP, and any other
required registers.
9) PCDOS EXEC function 3 (overlay) lives in the transient piece
of COMMAND.COM and gets loaded when needed, thus the
requirement for enough free space to load the EXEC loader
(about 1.5k). Under MS-DOS the EXEC system call lives in
the system space.
10) If you try to overlay an .EXE file with the high/low switch set
to load the in the upper end of memory nothing will happen.
The high/low switch is only for process creation, not for
overlays.
11) DOS 2.x destroys all registers, including SS:SP.
12) (AL=04h) This is DOS 4.0 as released in 1987 to various
European OEMs. It is not related to US DOS 4.0.
13) This call is explicitly supported by the OS/2 1.x DOS
Compatibility Box.
14) TOS: $4B EXEC.
15) New with DOS 5.0. Sets up for EXEC, including setting the DOS
version number returned by SETVER/int 21h,fn 30h. If DOS is
installed in the HMA this function turns off the A20 line,
making the HMA inaccessible. If your program needs the HMA
you must turn it back on before EXECing. DOS normally turns
the A20 line back on when called for normal system functions.
Your program must call EXEC immediately after this subfunction.
You may not call any DOS, BIOS, or system interrupts between
this subfunction and loading your program.
15) When in TopView this call is checked to ensure none of the
addresses are outside the application's memory partition.
16) This call is documented in the MS 5.0 TR, and in the PC-MOS/386
TR.
17) Some applications use their own EXEC scheme instead of calling
this function. Since DOS 5 enhanced the EXEC functions these
programs might not work, so Microsoft added a new set of
functions called EnterExecState. If a self-EXECing program
calls EnterExecState before EXECing, DOS 5 will do various
internal fixups to keep things happy.
Function 4Ch Terminate a Process (EXIT)
Quit with ERRORLEVEL exit code
entry AH 4Ch
AL exit code in AL when called, if any, is passed to next
process
return none
note 1) Control passes to DOS or calling program.
2) Return code from AL can be retrieved by ERRORLEVEL or function
4Dh.
3) All files opened by this process are closed, buffers are
flushed, memory is released, any network file region locks are
released, and the disk directory is updated.
4) Restores: Terminate vector from PSP:000Ah
Ctrl-C vector from PSP:000Eh
Critical Error vector from PSP:0012h
5) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
6) TOS: $4C TERM. Returns 2-byte errorlevel to calling program
7) Under DOS 3.1+ networks, all file locks should be removed
before terminating the program.
Function 4Dh Get Return Code of a Subprocess (WAIT)
Get return from functions 31h and 4Dh (ERRORLEVEL)
entry AH 4Dh
return AH circumstance which caused termination
00h normal termination
01h control-break or control-C
02h critical device error
03h terminate and stay resident (function 31h)
AL exit code of subprogram (functions 31h or 4Ch)
note 1) The exit code is only returned once (the first time).
2) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
3) Many programmers have wondered where DOS stores this
information, so they might access it multiple times or set it
directly. This is a version-dependent area that changes with
every release of DOS.
Function 4Eh Find First Matching File (FIND FIRST)
entry AH 4Eh
CX search attributes (see function 43h)
DS:DX segment/offset pointer to ASCIIZ filename
(with attributes)
return CF set AX error code (02h, 03h, 12h)
clear data block written at current DTA
format of block is: (info from BIX)
documented by Micro- |00h 1 byte attribute byte of search
soft as "reserved for |01h 1 byte drive letter for search
DOS' use on subsquent |02h 11 bytes the search name used
Find Next calls" |0Ch 2 bytes word value of last entry
function 4Fh |0Fh 4 bytes dword pointer to this DTA
|13h 2 bytes word directory start
| PC-DOS 3.10 (from INTERRUP.ARC)
|00h 1 byte drive letter
|01h-0Bh 11 bytes search template
|0Ch 1 byte search attributes
| DOS 2.x (and DOS 3.x except 3.1?)
(from INTERRUP.ARC)
|00h 1 byte search attributes
|01h 1 byte drive letter
|02h-0Ch 11 bytes search template
|0Dh-0Eh 2 bytes entry count within directory
|0Fh-12h 4 bytes reserved
|13h-14h 2 bytes cluster number of parent
directory
15h 1 byte file attribute
16h 2 bytes file time, bit mask:
0-4 half-seconds
5-10 minute
11-15 hour
18h 2 bytes file date, bit mask:
0-4 day
5-8 month
9-15 years since 1980
1Ah 2 bytes low word of file size
1Ch 2 bytes high word of file size
1Eh 13 bytes name and extension of file
found, plus 1 byte of 0s. All
blanks are removed from the name
and extension, and if an
extension is present it is
preceded by a period.
note 1) This function does not support network operations.
2) Wildcards are allowed in the filespec.
3) If the attribute is zero, only ordinary files are found. If the
volume label bit is set, only volume labels will be found. Any
other attribute will return that attribute and all normal files
together.
4) To look for everything except the volume label, set the hidden,
system, and subdirectory bits all to 1.
5) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
6) TOS: $4E SFIRST.
7) There is a reported anomaly in MS-DOS 2.11. Odd things happen
when you give it "C:\" as a file name. FindFirst reports it as
a valid file and Open returns a handle. If you read it twice
DOS reports an FAT error and aborts. You can demonstrate this
by:
FIND "whatever" c:\ [twice]
Int 21h/AH=044 AL=0 returns the handle as a NUL device which
makes a certain amount of sense since C:\ is a null terminated
string. The programming solution is to trap 'C:\' before it's
used.
8) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. ES:EBX
is a pointer to a 43-byte data area used instead of the DTA.
Format:
0-20 reserved for MOS
21 attribute
22-23 time of last update
24-25 date of last update
26-29 file size in bytes
30-42 found filename, followed by 00h
Function 4Fh Find Next Matching File (FIND NEXT)
Find next ASCIIZ file
entry AH 4Fh
return CF clear data block written at current DTA
set AX error code (02h, 12h)
note 1) If file found, DTA is formatted as in call 4Eh.
2) Volume label searches using 4Eh/4Fh reportedly aren't 100%
reliable under DOS 2.x. The calls sometime report there's a
volume label and point to a garbage DTA, and if the volume
label is the only item they sometimes won't find it. Most
references recommend the use of the older FCB calls for dealing
with the volume labels.
3) This function does not support network operations.
4) Use of this call assumes that the original filespec contained
wildcards.
5) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
6) TOS: $4F SNEXT.
7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. ES:EBX
is a pointer to a 43-byte data area used instead of the DTA.
Format:
0-20 reserved for MOS
21 attribute
22-23 time of last update
24-25 date of last update
26-29 file size in bytes
30-42 found filename, followed by 00h
Function 50h "Used Internally by DOS" - Set PSP or SetPID
* Set new Program Segment Prefix (current Process ID)
entry AH 50h
BX segment address of new PSP
return none - swaps PSPs regarded as current by DOS
note 1) By putting the PSP segment value into BX and issuing call 50h
DOS stores that value into a variable and uses that value
whenever a file call is made.
2) Note that in the PSP (or PDB) is a table of 20 (decimal) open
file handles. The table starts at offset 18h into the PSP. If
there is an 0FFh in a byte then that handle is not in use. A
number in one of the bytes is an index into an internal FB
table for that handle. For instance the byte at offset 18h is
for handle 0, at offset 19h handle 1, etc. up to 13h. If the
high bit is set then the file associated by the handle is not
shared by child processes EXEC'd with call 4Bh.
3) Function 50h is dangerous in background operations prior to DOS
3.x as it uses the wrong stack for saving registers. (same as
functions 0..0Ch in DOS 2.x). It doesn't use stack in 3.0+,
so it is safe to use in later versions of DOS.
4) Under DOS 2.x, this function cannot be invoked inside an int
28h handler without setting the Critical Error flag.
5) Open file information, etc. is stored in the PSP DOS views as
current. If a program (eg. a resident program) creates a need
for a second PSP, then the second PSP should be set as current
to make sure DOS closes that as opposed to the first when the
second application finishes.
6) See PC Mag Vol.5, No 9, p.314 for discussion, also used in
their BCOPY.ASM utility.
7) Used by DOS 3.3 PRINT & DEBUG, DesQview 2.01, Windows 1.03,
SYMDEB from MASM 4.0.
8) This call is available in the OS/2 1.x DOS Compatibility Box.
9) DOS stores the PID in one location, but the actual address is
version dependent. The strategy is to find the PID and thereby
find its address. If you have its address, you can swap PIDs
from the TSR pop-up code by peeking and poking. In the
initialization code, use function 51hto get the PID. You
know that DOS lives between the interrupt vectors 0:0 - 0:100
and that PID. Other programs might be in there, but DOS is
too. Search that memory for a copy of the PID. When you find
one, use this function to set a phony PID. If the location
where you found the original PID changes to the phony PID,
you have found the address of the PID. Don't forget to reset
the PID with SetPID after each test. DOS 2.0 and 2.1 maintain
the PID in two locations, not one.
Function 51h Get Program Segment Prefix (GetPID)
Returns the PSP address of currently executing program
entry AH 51h
return BX address of currently executing program (process ID)
note format of PSP:
offset size description
00h 2 bytes program exit point
02h word memory size in paragraphs
04h byte unused (0)
05h 5 bytes CP/M style entry point (far call to DOS)
0Ah word terminate address (old int 22h)
0Ch word terminate segment
0Eh word break address (old int 23h)
10h word break segment
12h word error address (old int 24h)
14h word error segment
16h word parent PSP segment
18h 20 bytes DOS 2.0+ open files, 0FFh = unused
2Ch word DOS 2.0+ environment segment
2Eh dword far pointer to process's SS:SP
32h word DOS 3.x+ max open files
34h DOS 3.x+ open file table address
36h dword DOS 3.x+ open file table segment
38h 24 bytes unused by DOS versions before 3.3
50h 3 bytes DOS function dispatcher (FAR routine)
53h 9 bytes unused
55h FCB #1 extension
5Ch 16 bytes FCB #1, filled in from first command
line argument
6Ch 20 bytes FCB #2, filled in from second command
line argument
80h128 bytes command tail / default DTA buffer
note 1) Used in DOS 2.x, 3.x uses 62h.
2) Function 51h is dangerous in background operations prior to DOS
3.x as it uses the wrong stack for saving registers. (same as
functions 0..0Ch in DOS 2.x). Doesn't use any DOS stacks in
DOS 3.0+.
3) 50h and 51h might be used if you have more than one process in
a PC. For instance if you have a resident program that needs
to open a file you could first call 50h to get the current ID
and then call 50h to set the ID to your PSP.
4) Under DOS 2.x, this function cannot be invoked inside an int
28h handler without setting the Critical Error flag.
5) Formerly "undocumented", now described in MS 5.0 TR.
6) This call is available in the OS/2 1.x DOS Compatibility Box.
FUNCTION 52h - see file 52h
provided with full version of DOSREF
Function 53h "Used Internally by DOS" - Translate BPB
* Translates BPB (BIOS Parameter Block, see below) into
a DOS Disk Block (see function call 32h).
entry AH 53h
DS:SI pointer to BPB (BIOS Parameter Block)
ES:BP pointer to buffer area for DOS Disk Block
Layout of BPB:
offset size description
00h-01h word bytes per sector, get from DDB bytes
02h-03h.
02h byte sectors per cluster, get from (DDB byte
4) + 1
03h-04h word reserved sectors, get from DDB bytes
06h-07h
05h byte number of FATs, get from DDB byte 08h
06h-07h word # of root dir entries, get from DDB bytes
09h-0Ah
for DOS 3.x: 08h-09h word total number of sectors, get from:
((DDB bytes 0Dh-0Eh) - 1) * (sectors per
cluster (BPB byte 2)) + (DDB bytes 0Bh-0Ch)
for DOS 4.x: set to zero if partition is larger than
32Mb, set dword at 15h to actual number
of sectors
0Ah word media descriptor byte, get from DDB byte
16h
0Bh-0Ch word number of sectors per FAT, get from DDB
byte 0Fh
for DOS 3.x: 0Dh word number of sectors per track
0Fh word number of heads
11h dword number of hidden sectors
15h 11 bytes reserved
for DOS 4.x: 15h dword total number of sectors if word at 08h
contains zero
return unknown
note This function is documented as 'SetDPB' in the Zenith MS-DOS
3.05 TRM.
Function 54h Get Verify Setting
Get verify flag status
entry AH 54h
return AL 00h if flag off
01h if flag on
note 1) Flag can be set with function 2Eh.
2) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
3) The verify state is off by default.
Function 55h "Used Internally by DOS" - Create "Child" PSP
* Create PSP: similar to function 26h (which creates a
new Program Segment Prefix at segment in DX) except
creates a "child" PSP rather than copying the existing
one.
entry AH 55h
DX segment number at which to create new PSP.
return unknown
note 1) This call is similar to call 26h which creates a PSP except that
unlike call 26h the segment address of the parent process is
obtained from the current process ID rather than from the CS
value on the stack (from the INT 21h call). DX has the new PSP
value and SI contains the value to be placed into PSP:2 (top of
memory).
2) Function 55 is merely a substitute for function 26h. It will
copy the current PSP to the segment address DX with the
addition that SI is assumed to hold the new memory top segment.
This means that function 26h sets SI to the segment found in the
current PSP and then calls function 55h.
Function 56h Rename a File
entry AH 56h
DS:DX pointer to ASCIIZ old pathname
ES:DI pointer to ASCIIZ new pathname
return CF clear successful rename
set AX error code (02h, 03h, 05h, 11h)
note 1) Works with files in same logical drive only.
2) Wildcard characters not allowed in filename.
3) The name of a file is its full pathname. The file's full
pathname can be changed while leaving the actual FILENAME.EXT
unchanged. Changing the pathname allows the file to be
"moved" from subdirectory to subdirectory on a logical drive
without actually copying the file.
4) DOS 3.x allows renaming of directories.
5) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
6) TOS: $56 RENAME. Similar to MS-DOS 2.x.
7) Under DOS 3.1+ networks, the user must have Read and Create
access to the affected directories.
8) For PC-MOS/386 native mode, use DS:EDX and ES:EDI instead of
DS:DX and ES:DI.
Function 57h Get/Set a File's Date and Time
Read or modify time and date stamp on a file's directory
entry
entry AH 57h
AL function code
00h Get Date and Time
01h Set Date and Time
CX time to be set
DX date to be set
02h unknown (DOS 4.0+)
03h unknown
04h unknown (DOS 4.0+)
BX file handle
return CF clear CX time of last write (if AL = 0)
DX date of last write (if AL = 0)
set AX error code (01h, 06h)
note 1) Date/time formats are:
CX bits 0Bh-0Fh hours (0-23)
05h-0Ah minutes (0-59)
00h-04h #2 sec. incr. (0-29)
DX bits 09h-0Fh year (relative to 1980)
05h-08h month (0-12)
00h-04h day of the month (0-31)
2) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
3) TOS: $57 GSDTOF.
Function 58h Get/Set Allocation Strategy (DOS 3.0+)
entry AH 58h
AL 00h Get Current Strategy (see 01h)
Used to obtain the current allocation strategy.
First Fit is the normal default.
01h Set New Current Strategy
BL new strategy
00h First Fit - chooses the lowest block in
memory which will fit (this is the
default). (use first memory block large
enough)
01h Best Fit - chooses the smallest block
which will fill the request.
02h Last Fit - chooses the highest block
which will fit.
(DOS 5.0) 40h FIRST_FIT_HIGHONLY - search upper memory
area for the lowest available block
(DOS 5.0) 41h BEST_FIT_HIGHONLY - search upper memory
area for the smallest block that fits
the request
(DOS 5.0) 42h LAST_FIT_HIGHONLY - search upper memory
area for the highest available block
(DOS 5.0) 80h FIRST_FIT_HIGH - search upper memory
area for the lowest available block. If
no block found, load in conventional
memory
(DOS 5.0) 81h BEST_FIT_HIGH - seach the upper memory
area for the closest match to the
requested size. If no match is found,
load in convenional memory.
(DOS 5.0) 82h LAST_FIT_HIGH - search the upper memory
area for the available block at the
highest address. If no block is found,
load in conventional memory.
02h Get UMB Link State
Indicates if high DOS memory arenas are
currently part of the conventional DOS memory
arena.
03h Set UMB Link State
BX 00h Unlink High DOS memory blocks
01h Link High DOS memory blocks
note: Adds or removes high memory blocks from
the DOS arena. Returns an error if no
high arenas exist.
return CF clear successful
(AL=00) AX strategy code (see 01h) For DOS 5.0+,
(AL=02) AL 00h if upper memory area is not linked
01h if the upper memory area is linked
set error
AX error code (01h)
(AL=03) AX 0001h invalid function if DOS was
loaded without DOS=UMB
0007h memory arena trashed
note 1) A program that changes the allocation strategy or the high DOS
link state should ALWAYS restore it to its original condition
before exiting, or subsequent programs may fail.
2) The set subfunction accepts any value in BL; 2 or greater means
last fit. The get subfunction returns the last value set, so
programs should check whether the value is greater than or equal
to 2.
3) For discussion of best fit vs. first fit allocation strategies,
see Knuth, *Fundamental Algorithms.* Very briefly, Knuth finds
that first fit methods are far superior to best fit, which
increases both allocation overhead and memory fragmentation.
The "last" fit that DOS offers is nothing other than a first
fit, starting the search at the other end of the chain (the
algorithm still takes the first fitting block that is
encountered in the search).
4) For DOS 5+, the default scheme is "allocate high first". This
is actually a variant of the previous first/best/last
allocation options. When enabled, the high-first strategy
causes DOS to begin its free block search at the first UMB. If
DOS can't find enough memory in the UMB, it searches from the
beginning of conventional memory. As a result, high-first may
result in a worse fit than best fit alone if there is a better
fit low than high.
Function 59h Get Extended Error Code (DOS 3.0+)
The Get Extended Error function call (59h) is intended to provide
a common set of error codes and to supply more extensive
information about the error to the application. The information
returned from function call 59h, in addition to the error code,
is the error class, the locus, and the recommended action. The
error class provides information about the error type (hardware,
internal, system, etc.). The locus provides information about
the area involved in the failure (serial device, block device,
network, or memory). The recommended action provides a default
action for programs that do not understand the specific error code.
Newly written programs should use the extended error support
both from interrupt 24h hard error handlers and after any int
21h function calls. FCB function calls report an error by
returning 0FFh in AL. Handle function calls report an error by
setting the carry flag and returning the error code in AX. Int
21h handle function calls for DOS 2.x continue to return error
codes 0-18. Int 24h handle function calls continue to return
error codes 0-12. But the application can obtain any of the
error codes used in the extended error codes table by issuing
function call 59h. Handle function calls for DOS 3.x can return
any of the error codes. However, it is recommended that the
function call be followed by function call 59h to obtain the
error class, the locus, and the recommended action.
The Get Extended Error function (59h) can always be called,
regardless of whether the previous DOS call was old style (error
code in AL) or new style (carry bit). It can also be used inside
an int 24h handler.
You can either check AL or the carry bit to see if there was no
error, and call function 59h only if there was an error, or take
the simple approach of always calling 59h and letting it tell you
if there was an error or not. When you call function 59h it will
return with AX=0 if the previous DOS call was successful.
Various versions of IBM's DOS, MSDOS, OEM customized versions
of MSDOS, Digital's DRDOS, and other DOS emulating environments
sometimes return different error codes for the same function.
Be careful if you are testing for one specific error condition.
entry AH 59h
BX version code (0000 for DOS 3.0 and 3.1)
return AX extended error code:
01h Invalid function number 2.0+
02h File not found 2.0+
03h Path not found 2.0+
04h Too many open files, no file handles left 2.0+
05h Access denied 2.0+
06h Invalid handle 2.0+
07h Memory control blocks destroyed 2.0+
08h Insufficient memory 2.0+
09h Invalid memory block address 2.0+
0Ah Invalid environment 2.0+
0Bh Invalid format 2.0+
0Ch Invalid access code 2.0+
0Dh Invalid data 2.0+
0Eh Reserved 2.0+
0Fh Invalid drive was specified 2.0+
10h Attempt to remove the current directory 2.0+
11h Not same device 2.0+
12h No more files 2.0+
13h Tried to access write-protected diskette 2.0+
14h Unknown unit 2.0+
15h Drive not ready 2.0+
16h Unknown command 2.0+
17h Bad CRC check 2.0+
18h Bad request structure length 2.0+
19h Seek error 2.0+
1Ah Unknown media type 2.0+
1Bh Sector not found 2.0+
1Ch Printer out of paper 2.0+
1Dh Write fault 2.0+
1Eh Read fault 2.0+
1Fh General failure 2.0+
20h Sharing violation 3.0+
21h Lock violation 3.0+
22h Invalid disk change 3.0+
23h FCB unavailable 3.0+
24h Sharing buffer overflow 3.3+
25h Bad code page 4.0+
26h Handle EOF 4.0+
27h Handle disk full 4.0+
28h Reserved
29h "
2Ah "
2Bh "
2Ch "
2Dh "
2Eh "
2Fh "
30h "
31h Reserved
32h Network: request not supported 3.1+
33h Network: remote computer not listening 3.1+
34h Network: duplicate name on network 3.3+
35h Network: name not found 3.3+
36h Network: busy 3.3+
37h Network: device no longer exists 3.3+
38h Network: NETBIOS command limit exceeded 3.3+
39h Network: adapter hardware error 3.3+
3Ah Network: incorrect response from network 3.3+
3Bh Network: unexpected network error 3.3+
3Ch Network: incompatible remote adapter 3.3+
3Dh Network: print queue full 3.3+
3Eh Network: not enough space for print file 3.3+
3Fh Network: print file was deleted 3.3+
40h Network: name was deleted 3.3+
41h Network: access denied 3.3+
42h Network: device type incorrect 3.3+
43h Network: name not found 3.3+
44h Network: name limit exceeded 3.3+
45h Network: NETBIOS session limit exceeded 3.3+
46h Network: sharing temporarily paused 3.3+
47h Network: request not accepted 3.3+
48h Network: print or disk redirection paused 3.1+
49h Reserved
4Ah "
4Bh "
4Ch "
4Dh "
4Eh "
4Fh Reserved
50h File exists 3.3+
51h Reserved 3.3+
52h Cannot make directory entry 4.0+
53h Fail on interrupt 24h 3.3+
54h Network: too many redirections 3.3+
55h Network: duplicate redirection 3.3+
56h Invalid password 3.3+
57h Invalid parameter 3.3+
58h Network: data fault (write error) 3.3+
59h Reserved
5Ah Comp not loaded 5.0+
BH class of error: (DOS 5.0 name)
01h Out of resource ERRCLASS_OUTRES
(not enough disk space, etc)
02h Temporary situation ERRCLASS_TEMPSIT
(not an error, but a temporary situation that is
expected to end, such as a locked region in a
file)
03h Authorization ERRCLASS_AUTH
(denied access - sharing or network)
04h Internal ERRCLASS_INTRN
(DOS internal error)
05h Hardware failure ERRCLASS_HRDFAIL
(bad floppy or HD controller, etc.)
06h System failure ERRCLASS_SYSFAIL
(error not due to executing program, such as
missing configuration or data files)
07h Application program error ERRCLASS_APPERR
(executing program bombed)
08h Not found ERRCLASS_NOTFND
(file or device not found)
09h Bad format ERRCLASS_BADFMT
(file or item invalid format or type)
0Ah Locked ERRCLASS_LOCKED
(network or SHARE lock)
0Bh Media error ERRCLASS_MEDIA
(wrong volume ID, disk failure)
0Ch Already exists ERRCLASS_ALREADY
(file or device already exists)
0Dh Unknown ERRCLASS_UNK
(Smurfs infesting system board)
BL suggested action code:
01h Retry ERRACT_RETRY
02h Delayed retry ERRACT_DLYRET
03h Prompt user ERRACT_USER
04h Abort after cleanup ERRACT_ABORT
05h Immediate abort ERRACT_PANIC
06h Ignore ERRACT_IGNORE
07h Retry after user intervention ERRACT_INTRET
CH locus (where error occurred):
01h Unknown or not appropriate ERRLOC_UNK
02h Block device ERRLOC_DISK
03h Network related ERRLOC_NET
04h Serial device ERRLOC_SERDEV
05h Memory related ERRLOC_MEM
note 1) Not all DOS functions use the carry flag to indicate an error.
Carry should be tested only on those functions which are
documented to use it.
2) None of the DOS functions which existed before 2.0 use the
carry indicator. Many of them use register AL as an error
indication instead, usually by putting 0FFh in AL on an error.
Most, but not all, the "new" (2.x, 3.x) functions do use carry,
and most, but not all, of the "old" (1.x) functions use AL.
3) On return, CL, DI, DS, DX, ES, BP, and SI are destroyed - save
before calling this function if required.
4) DOS 2.x Error Codes: If you are using function calls 38h-57h
with DOS 2.x, to check if an error has occurred, check for the
following error codes in the AX register:
call| error code call| error code call| error code
----|-------------------|--------------------|----------------
38h | 2 41h | 2,3,5 4Ah | 7,8,9
39h | 3,5 42h | 1,6 4Bh | 1,2,3,5,8,10,11
3Ah | 3,5,15 43h | 1,2,3,5 4Eh | 2,3,18
3Bh | 3 44h | 1,3,5,6 4Fh | 18
3Ch | 3,4,5 45h | 4,6 56h | 2,3,5,17
3Dh | 2,3,4,5,12 46h | 4,6 57h | 1,6
3Eh | 6 47h | 15
3Fh | 5,6 48h | 7,8
40h | 5,6 49h | 7,9
5) Note that extended error codes 13h through 1Fh correspond to
error codes 00h through 0Ch returned by int 24h.
6) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
Function 5Ah Create Temporary File
Create unique filename (for temporary use) (DOS 3.0+)
entry AH 5Ah
DS:DX pointer to buffer containing an ASCIIZ directory
pathname ending with a backslash (\). The buffer must
have at least 13 bytes free following the backslash,
as the file name and extension will be written there.
CX file attribute (00h, 01h, 02h, 04h, 20h only)
return CF clear AX handle
DS:DX new ASCIIZ pathname
set AX error code (03h, 04h, 05h)
note 1) The file created is not truly "temporary". It must be removed
by the user.
2) If the filename created already exists in the current
directory, this function will call itself again with another
unique filename until a truly unique filename is found.
3) The temporary filename usually consists of mixed letters and
numbers. No file extension appears to be generated.
4) DOS 3.0-4.01 used mixed letters and numbers. MS DOS 5.0 appears
to use letters only. DR DOS 5.0 appears to use numbers only.
5) Under DOS 3.1+ and NETBIOS compatible networks, DOS opens the
file in compatibility mode.
6) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 5Bh Create a New File (DOS 3.0+)
entry AH 5Bh
DS:DX segment/offset pointer to an ASCIIZ pathname
CX file attribute (00h, 01h, 02h, 04h, 20h only)
return CF clear AX file handle
DS:DX new ASCIIZ pathname
set AX error code (03h, 04h, 05h, 50h)
note 1) Unlike function 3Ch, function 5Bh will fail if the file already
exists. This is useful on networks, since another application
might create a file of the same name with 3Ch first, causing
the first 3Ch to fail. Use of this call instead of 3Ch is good
practice for code that will not need to run under DOS 2.x.
2) Under DOS 3.1+ networks, DOS opens the file in read/write mode.
This call will fail if the user does not have Create access.
3) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
4) The MSDOS Encyclopedia suggests this call may be used to
implement semaphores in LANs or multitasking environments. A
zero-byte marker file could be created to indicate semaphore set.
5) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX.
Function 5Ch Lock/Unlock File Access (DOS 3.0+)
entry AH 5Ch
AL 00h to lock file region
01h to unlock file region
BX file handle
CX:DX 4-byte starting offset from beginning of file of region
to lock
SI:DI 4-byte integer, high/low size of region to lock
(in bytes)
return CF clear successful
set AX error code (01h, 06h, 21h, 24h)
note 1) Unlock all files before exiting or undefined results may occur.
Programs using file locking should trap int 23h (Control-C
Handler Address) and int 24h (Critical Error Handler Address)
and unlock files before returning to the caller.
2) Programs spawned with EXEC inherit all the parent's file
handles but not the file locks.
3) This call is explicitly supported in the OS/2 1.x DOS
Compatibility Box.
4) You may lock an entire file, any part of a file, or several
parts of the same file. For example, it would be more
efficient to lock an area in a database containing a single
record than to lock the entire file. If two adjacent sections
of a file are locked separately, they must be unlocked
separately - you cannot change the lock pointers and use a
single unlock call.
5) You should lock only as much of a file as you need and keep
the lock only for as long as necessary. Should a file need to
be shared and updated often, continual locking and unlocking
can slow file access detectably.
6) This call returns error 01h if SHARE is not loaded.
7) Locked files must be unlocked before the program terminates,
or the result is undefined.
8) A transaction-oriented algorithm for using locking is
recommended. In effect, assert lock, read data, change data,
remove lock. An application should release its lock when a
transaction is complete.
9) Locking past end-of-file does not cause an error.
10) Locking a portion of a file with fn 5Ch denies all other
processes both read and write access to the locked region.
11) For PC-MOS/386 native mode, use ECX and EDX instead of CX:DX.
Function 5Dh Multifunction, DOS Internal - partial (DOS 3.x+)
entry AH 5Dh
AL subfunction
00h Indirect Function Call
DS:DX pointer to buffer containing register
values AX, BX, CX, DX, SI, DI, DS, ES
for a call to int 21h
return as appropriate for function being called
note Does not check AH. Out of range values
will crash the system.
01h SYNC? (DOS 3.1+)
parameters unknown
note 1) Does something to each disk file in the
system. File Table which has been
written to.
2) If remote file, calls int 2Fh/fn1107h.
3) Seems to update the time stamp of all
open files which have been written to.
02h SHARE.EXE? (DOS 3.1+)
note Error unless SHARE is loaded
(calls fn 52h+4Ah)
03h SHARE.EXE? (DOS 3.1+)
note Error unless SHARE is loaded
(calls fn 52h+4Ah)
04h SHARE.EXE functions? (DOS 3.1+)
note Error unless SHARE is loaded
(calls fn 52h+4Ah)
05h Network functions? (DOS 3.1+)
DS:DX pointer to buffer (see AX=0Ah), only
fields at offset 12h, 14h used
note Error unless SHARE is loaded
(calls fn 52h+5Ah)
06h Get Address of Critical Error Flag
DS:DX pointer to buffer (see 0Ah), only
fields at offset 12h, 14h used
return CX unknown value
DX unknown value
DS:SI pointer to critical error flag
notes This call does a lot of other work in
addition to returning the pointer.
Setting the CritErr flag allows use of
functions 50h/51h from int 28h under
DOS 2.x by forcing use of correct stack.
(LANtastic) 07h Return Redirected Printer mode
return DL 00 output is combined
01h output is separated
note The current printer mode (either
printer output combined or separated)
is returned.
(LANtastic) 08h Set Redirected Printer Mode
DL 00h set redirected output to be
combined
01h set redirected output to be
separated. (implicitly starts
a new print job)
return none
note 1) The current printer mode (either printer
output combined or separated) can be set.
2) may be used by COMMAND.COM
(LANtastic) 09h Flush Printer Output
return none
note 1) Printer output is flushed and a new
print job is started. If no output
exists to be flushed then this function
has no effect.
2) may be used by COMMAND.COM
09h unknown - may be used by COMMAND.COM
(DOS 5, doc'd) 0Ah Set Extended Error Information
DS:DX address of 11-word error information
table:
format of error information table:
offset size description
00h word value that next call to
fn 59h will return in AX
02h word value that next call to
fn 59h will return in BX
04h word CX
06h word DX
08h word SI
0Ah word DI
0Ch word DS
0Eh word ES
10h word reserved (set to 0)
12h word user (computer) ID,
0=local
14h word program ID, 0=local
program
return none
return DS:SI (for 06h) pointer to critical error flag
note 1) Function 0Ah; DOS 3.1+.
2) Function 06h; setting CritErr flag allows use of functions
50h/51h from int 28h under DOS 2.x by forcing the use of the
correct stack.
3) Functions 07h, 08h, 09h are identical in DOS 3.1 and call int
2Fh fn 1125h.
Function 5Eh Network Printer
DOS 3.1+ with Networks software
PC-MOS/386 through 4.1 has limited support for functions
5Eh through 5F04h. The MOS NETBIOS driver must be
loaded. A device name is returned for 5E00h and an
"end of list" status is returned for other functions.
entry AH 5Eh
AL 00h Get Machine Name
DS:DX pointer to 16-byte buffer for ASCIIZ name
return CH 00h if name not defined
<>0 name is defined
CL 00h name not set
<>0 NetBIOS name number
DS:DX pointer to ASCIIZ name if CH <>0
CF set on error
AX error code (01h)
note 1) The ASCIIZ name is a 15 byte string
padded to length with zeroes.
2) The NETBIOS number in CL and name at
DS:DX are valid only if the value
returned in CH is <>0.
01h Set Machine Name
CH 00h undefine name
<>0 define name
CL name number
DS:DX pointer to ASCIIZ name
02h Set Printer Control String
BX redirection list index
CX length of setup string (max 64 bytes)
DS:SI pointer to ASCIIZ setup string buffer
return: CF set on error
AX error code (01h)
note 1) Set printer setup sets a setup string
to be sent to the network printer
whenever a file is queued to the
printer.
2) LANtastic LANOS does not process this
request since printer setup strings are
controlled by the system administrator
using the NET_MGR program. The system
call does not return an error, however.
03h Get Printer Control String
BX redirection list index
ES:DI pointer to 64-byte string buffer
return CX length of setup string
(maximum 64 bytes)
return: CF set on error
AX error code (01h)
note 1) This call will return the setup string
set with fn 02h above.
2) LANtastic LANOS does not process this
request since printer setup strings are
controlled by the system administer
using the NET_MGR program. The system
call does not return an error, however,
and the length of the setup string (CX)
is 0.
04h DOS 3.1+ +Microsoft Networks - unknown
note Calls int 2F/AX=111Fh with 5E04h on
stack.
05h DOS 3.1+ +Microsoft Networks - unknown
note Calls int 2F/AX=111Fh with 5E05h on
stack.
06h DOS 3.1+ +Microsoft Networks - unknown
note Calls int 2F/AX=111Fh with 5E06h on
stack.
return CF clear successful
set error
AX error code (01h for all listed subfns)
note 1) Used in IBM's & Microsoft's Network programs.
2) Partial documentation in Fall 1985 Byte, in Advanced MS-DOS,
in MS-DOS Encyclopedia, LANtastic Programmer's Manual.
3) These services require that the network software be installed.
4) SHARE must be loaded or results can be unpredictable on 00h,
or fail with 02h or 03h.
5) The redirection entry index is an index into a table that
identifies the printer as a device on the network.
Function 5Fh Network Redirection
(DOS 3.1+ and Microsoft Networks)
entry AH 5Fh
AL *00h Unknown
*01h Unknown
02h Get Redirection List Entry
BX redirection entry index. Index 0
specifies the first entry
DS:SI pointer to 16 byte area which will
receive the ASCIIZ local device name
ES:DI pointer to 128 byte buffer for the
ASCIIZ network device name
return CF set on error
AX error code (01h, 12h)
BH device status flag
(bit 0=0 if valid)
(bit 0=1 if invalid)
(bits 1-7 reserved)
BL device type
03 printer device
04 drive device (file)
CX value stored by fn 03h call.
Should be 0 for compatiblity
with LAN OS
DS:SI pointer to 16 byte ASCIIZ local
device name
ES:DI pointer to 128 byte ASCIIZ
network name
note 1) DX and BP are destroyed by this call.
2) This call returns information about a
single redirected device (see fn 03h).
This fn may be used to scan the list of
redirected devices.
03h Redirect Device - Make Assign List Entry
Redirects a workstation drive or device to a
server directory or device.
AX error code if error
BL device type
03h printer device
04h file device
CX stored parameter value (0 for
compatibility with IBM PC Network
program and LANtastic)
DS:SI pointer to 16-byte ASCIIZ source
device name for printer: PRN, LPT1,
LPT2, LPT3
ES:DI pointer to destination 128-byte
ASCIIZ network path and ASCIIZ
password (e.g.,'\\machine_name\path',
0,'password',0)
return CF set on error
AX error code (01h, 03h,
05h, 08h, 0Fh, 12h)
note 1) Redirect device allows you to connect
local devices to network paths. For
example you can connect your LPT1 to
a printer on another node. References
to LPT1 are routed to the network.
2) If the password is omitted, the
pathname must be followed by two null
bytes.
3) For printer redirection, MS-Network
intercepts int 17h. When redirection
is canceled, all printing is sent to
the first local printer. (LPT1)
04h Cancel Redirection Assignment
DS:SI pointer to ASCIIZ device name or
network path to be canceled
return CF set on error
AX error code (01h, 03h,
05h, 08h, 0Fh, 12h)
note 1) Cancel device redirection allows you
to remove a device redirection so that
the device is restored to its former
state.
return CF clear successful
set if error
AX error code
(fn 02h) 01h, 12h
(fn 03h) 01h, 03h, 05h, 08h
(fn 04h) 01h, 0Fh
note 1) Used in IBM's Network program and Microsoft MS-Networks.
2) Partial documentation in Fall 1985 Byte, in Advanced MS-DOS,
in the MS-DOS Encyclopedia, LANtastic Programmer's Manual.
3) These services require that the network software be installed.
4) SHARE must be loaded or the call will fail.
5) The network device name requires a password.
6) Only printer and disk devices are supported for redirection.
STDAUX, STDIN, STDOUT, and STERR are not supported by the
Microsoft/IBM specification. Other companies have managed
to do this with various nonstandard additions to the API.
Function 60h Parse pathname (TRUENAME) (DOS 3.0+)
* Perform name processing on a string (internal to DOS)
entry AH 60h
DS:SI pointer to ASCIIZ source string (null terminated)
ES:DI pointer to destination 80 byte ASCIIZ string buffer
return ES:DI buffer filled with qualified name in form (drive):(path)
CF set error
AX error code (02h, 03h)
clear no error
note 1) Documented in Zenith 3.05 Technical Reference.
2) All name processing is performed on the input string; string
substitution is performed on the components, current drive/
directories are prepended, . and .. are removed. Under most
networking software, the drive letter is replaced with the node
name, i.e. returns pathname like \\SERVER\UTILS\TEST.TXT
instead of F:\UTILS\TEST.TXT.
3) Example: If current drive/directory is C:\TEST, MYFILE.X is
translated to C:\TEST\MYFILE.X; ..\SOURCE\SAMPLE.ASM is
translated to C:\SOURCE\SAMPLE.ASM.
4) It is the caller's responsibility to make sure DS:SI does not
point to a null string. If it does, SI is incremented, a null
byte is stored at ES:DI, and the routine returns.
5) Used by CHKDSK, at least in DOS 3.3, and DOS 3.x.
6) If path string is on a JOINed drive, the returned name is the
one that would be needed if the drive were not JOINed;
similarly for a SUBSTed drive letter. Because of this, it is
possible to get a qualified name that is not legal with the
current combination of SUBSTs and JOINs.
7) Used by DOS 4.0 SHELLC.EXE.
8) This call has been discovered in DOS versions as early as
2.11.
9) In Novell Netware 2.1x, this call is not supported when the
8th bit (high ASCII) is set on any letter in the file or
pathname, and when the file being inquired about is on a
remote drive. This causes problems with machines using
foreign code pages.
10) You need DPMI services to use this call under MS Windows 3.x.
There is an example in PC Magazine, 25 June 1991, p. 389
called TRUENAME.C.
Function 61h undocumented - (DOS 3.0)
* Internal to DOS - parameters not known
entry AH 61h
return AL 00h
note Supposedly documented in Zenith DOS 3.05 Technical Reference.
Function 62h Get Program Segment Prefix (PSP) (DOS 3.0+)
entry AH 62h
return BX segment address of PSP
note Under DOS 3.x+, this function does not use any of DOS' internal
stacks and is thus fully reentrant.
Function 63h Get Lead Byte Table (MS-DOS 2.25 only)
Added in DOS 2.25 for additional foreign character
set support.
entry AH 63h
AL subfunction
00h get system lead byte table address
01h set/clear interim console flag
DL 0000h to clear interim console flag
0001h to set interim console flag
02h get interim console flag
return DS:SI pointer to lead byte table (AL = 00h)
DL interim console flag (AL = 02h)
note 1) Function 63h destroys all registers except SS:SP on return.
To avoid saving registers repeatedly, a process can copy the
table or save the pointer for later use.
2) Works ONLY in MS-DOS 2.25!
3) Note fn 63h does not return errors in AL or CF.
4) Original support was for Kanji (Japanese) and Hanegul (Korean)
only.
5) The lead byte table contains pairs of bytes that represent the
inclusive boundary values for the lead bytes of the specified
alphabet. Because of the way bytes are ordered by the 8086
microprocessor family, the values must be read as byte values,
not as word values.
6) If the interim console flag is set (DL=0001h) by a program
through a call to fn 63h, the following int 21h functions
return interim character information on request: 07h, 08h,
0Bh, 0Ch.
Function 64h Undocumented - Used internally by DOS
entry AH 64h
return unknown
note 1) DOS 3.2+ internal function of some type? May be a network
function.
2) In DOS 3.31 it seems that when you load AL with a nonzero
number, int 28h will get called more often. AL=0 resets back
to the default "boot up" state.
Function 65h Get Extended Country Information (DOS 3.3+)
Returns information about the selected country
formats, code pages, and conversion tables
entry AH 65h
AL information ID code
01h get general internationalization info
02h get pointer to uppercase table (130 bytes max)
(maps chars 80h-0FFh to their uppercase
equivalents, if any; used mainly to map
accented or other vowels to the corresponding
plain vowels)
03h unknown
04h get pointer to filename uppercase table (130
bytes max) (similar to table for AL = 02h)
(DOS 5.0+) 05h get filename character table - specifies which
chars must not be used in filenames.
06h get pointer to collating sequence table (258
bytes max) (maps uppercase, lower, and
accented chars together for sorting)
07h get pointer to double-byte character set table
(DOS 5.0+) 20h convert character - converts character in DL to
uppercase using the current uppercase table
(DOS 5.0+) 21h convert string - converts string in DS:DX,
length CX to uppercase using current uppercase
table, returns in DS:DX
(DOS 5.0+) 22h convert ASCIIZ string - converts string in
DS:DX to uppercase using current uppercase
table, returns in DS:DX
BX code page (0FFFFh = current code page)
CX amount of information to be returned (minimum 5)
DX target country ID (0FFFFh = default current country)
ES:DI segment/offset pointer to country information buffer
return CF set on error
AX error code (02h)
otherwise:
CX size of country information returned
ES:DI pointer to country information:
offset length description
00h 1 byte info ID (for all following buffers)
If information ID code <> 1:
01h dword pointer to information
If information ID code = 1:
01h word length of remainder of buffer (<= 38)
03h word country ID
05h word code page number
07h 34 bytes same as for int 21h function 38h
If information ID code = 2:
01h word table size
05h dword pointer to uppercase table
128 bytes uppercase equivalents (if any) of chars 80h-0FFh
If information ID code = 4:
01h word table size
05h dword pointer to collating table
256 bytes values used to sort characters 00h-0FFh
If information ID code = 6:
01h word table size
05h dword pointer to filename uppercase table.
This table starts with a 2-byte length
field, then 256 ASCII values placed in
order
128 bytes uppercase equivalents (if any) of chars
80h-0FFh
If information ID code = 7: (DOS 4.0)
unknown
note 1) For AL=02h, 04h, or 06h, the first two bytes of the table
give its length and then a 128 byte table of uppercase ASCII
characters for 02h or 04h and a pointer to the collating
sequence for 06h.
2) The country code and code page must match. If not, error 02h
is in AX.
3) If more information is provided than was requested by CX, it
is truncated without generating an error.
4) Country information:
bytes description
01h value of AL (01h)
02h,03h size (max = 38)
04h,05h country code
06h,07h code page
08h,09h date format
0Ah,0Eh currency symbol
0Fh,10h thousands separator
11h,12h decimal separator
13h,14h date separator
15h,16h time separator
17h currency format flags
18h digits in currency
19h time format
20h-22h monocase routine entry point
23h-24h data list separator
25h-29h zeros
Function 66h Get/Set Global Code Page Table (DOS 3.3+)
Query/reset code page defaults
entry AH 66h
AL 00h Get Global Code Page
01h Set Global Page
BX active code page
DX system code page
(active page at boot time)
return CF clear successful
set AX error code (unknown)
if 00h BX active code page
DX system code page
(active page at boot time)
note 1) BX = active code page: 437 = US, 860 = Portugal, 863 = Canada
(French) 865 = Norway/Denmark, 850 =
multilingual
2) MS 5.0 TR shows fns as 01h and 02h.
Function 67h Set Handle Count (DOS 3.3+)
Supports more than 20 open files per process
entry AH 67h
BX desired number of handles (20 to 65,535)
return CF clear if OK
set if error
AX error code (unknown)
note 1) This function changes the 20-byte handle table pointer in the
PSP to point to a new, larger handle table elsewhere in memory.
2) The memory the 67h call allocates is taken from the normal
DOS pool, and is reclaimed on process termination, so nothing
is lost.
3) When calling this function you must release enough memory for
DOS to contain the extended handle list.
4) If the requested number of handles is less than 20 nothing
is done.
5) Early versions of PC-MOS/386 v4.1 did not properly deallocate
memory when the number of handles was reduced.
6) The error value returned in AX is not documented in the IBM
4.0 DOS Technical Reference, the MSDOS Encyclopedia or the MS
5.0 TR.
7) For PC-MOS/386 4.x, the only error code is 08h (insufficient
memory).
Function 68h Commit File (DOS 3.3+)
Write all buffered data to disk
entry AH 68h
BX file handle of previously opened file
return CF clear successful
set on error
AX error code (unknown)
note 1) Faster and more secure method of closing a file in a network
than current close commands.
2) This is effectively the same as DUPing the handle for a file
and then closing the new one, except that this call won't fail
if the system is out of handles.
3) The file's buffers are flushed and its directory and FAT
entries are updated.
4) The error value returned in AX is not documented in the IBM
4.0 DOS Technical Reference, the MSDOS Encyclopedia or the MS
5.0 TR.
5) For PC-MOS/386 4.x, the error codes are 06h (invalid handle)
and 22h (wrong disk).
Function 69h Disk Serial Number DOS 4.0+ (US versions)
Handles "Volume Serial Number" on disks formatted with
DOS 4.0+
entry AH 69h Get Volume Serial Number
AL 00h get serial number
01h set serial number
BL drive (0=default, 1=A, etc)
DS:DX pointer to disk information table
return CF set on error
AX error code
clear if successful
AH destroyed
AL (fn 00h) buffer filled with appropriate values
from extended BPB
(fn 01h) extended BPB on disk set to values
from buffer
DS:DX disk information table. Format:
offset size description
00h word unknown (zeroes on my system)
02h dword disk serial number (binary)
06h 11 bytes volume label or "NO NAME " if none
11h 8 bytes FAT type - string "FAT12 " or
"FAT16 "
note 1) The FAT type field refers to the number of bits per directory
entry.
2) Does not generate a critical error; all errors are returned
in AX.
3) Error 0005h given if no extended BPB on disk.
4) Does not work on network drives (error 0001h).
5) Buffer after first two bytes is exact copy of bytes 27h thru
3Dh of extended BPB on disk.
6) FORMAT (in DOS 5.0) does not call int 21h/fn 69h. (Get/Set
Volume Serial Number) For floppy disks, it calls int 21h/fn
440Dh, CH=08, CL=46 [Set Media ID], and passes the serial
number. (from dsparks, BIX)
Function 6Ah Unknown (DOS 4.0?)
Function 6Bh Unknown (DOS 4.0?)
Function 6Ch Extended Open/Create DOS 4.0+ (US)
Combines functions available with Open, Create, Create
New, and Commit File
entry AH 6Ch
AL 00h reserved [which means there might be other
subfunctions?]
BX mode format 0WF0 0000 ISSS 0AAA
AAA is access code (read, write,
read/write)
SSS is sharing mode
I 0 pass handle to child
1 no inherit [interesting!]
F 0 use int 24h for errors
1 disable int 24h for all
I/O on this handle; use
own error routine
W 0 no commit
1 auto commit on all writes
CX create attribute
bits 0 read only
1 hidden
2 system
3 volume label
4 reserved
5 archive
6-15 reserved
DH 00h (reserved)
DL action if file exists/does not exists
bits 0-3 action if file exists
0000 fail
0001 open
0010 replace/open
4-7 action if file does not exist
0000 fail
0001 create
DS:SI pointer to ASCIIZ file name
return CF set on error
AX error code (unknown)
clear
AX file handle
CX action taken
01h file opened
02h file created/opened
03h file replaced/opened
note When APPEND is installed, if DX=xx1x it looks only in current
directory, if DX=xx0x it will search the full append path.
DX is called the open flag and gives what action to take if
the file exists or does not exist.
Function 89h undocumented - DOS_Sleep
* Not documented by Microsoft
entry AH 89h
return unknown
note 1) Function included in Microsoft C 4.0 startup code MSDOS.INC.
2) Debugging shows that the first instruction on entry to DOS
compares AH with 64h (at least in DOS 3.2) and aborts the
call if AH > 64.
3) Possibly used in European MSDOS 4.0?
Aftermarket Application Installed Function Calls:
Novell Netware 2.11:
Novell no longer recommends the int 21h method for invoking
the Netware functions. Int 21h will be supported
indefinitely, but the new net API calls for addressing the
software through the Multiplex Interrupt (2Fh). You may
address the API through int 2Fh in the same manner as int 21h;
only the interrupt number is different.
Novell API calls are referenced in Chapter 13. Most functions
from 0B6h through 0F9h are preempted by NetWare; if your
software uses any of these calls for another purpose it will
likely not run under NetWare.
NOTE: Novell (and most others') network software and SoftLogic's
DoubleDOS conflict on the following int 21h functions
0EAh-0EEh. Netware must use int 2Fh functions instead of 21h
functions if DoubleDOS will be used on the network.
Functions 0E0h - 0F6h: used by AI Architects/Ergo Computing
DOS extender
Functions 0E4h - 0EEh: used by DoubleDOS task switcher
Function 0FEh Enable Reader v4.0 API
Enable Reader is a speech synthesizer interface for
the blind. It will save all registers except the
flags, where the zero flag will be set if the call was
not one of the available Enable Reader 4.0 functions.
entry AH 0FEh
AL 01h Driver Output
DL Character To Output
return none
note The Driver Output call will output the character in DL through
the Enable Reader driver, without turning off the Help
Functions. It will be filtered by the ASCII sort routine in
the Enable Reader Driver, and if it is punctuation it will be
sent according to the level of punctuation selected.
entry AH 0FEh
AL 02h Direct Output
DL ASCII character to output
return none
note The Direct Output call will send the byte in DL directly to
the synthesizer, bypassing the Enable Reader driver and ASCII
filter sort routine.
entry AH 0FEh
AL 03h Message Output
DL character to output
return none
note The Message Output call allows character filtration and
punctuation, but turns off the Help functions in the driver.
entry AH 0FEh
AL 41h (ASCII A) Auto
return none
note The AUTO call turns the Spell mode on or off.
entry AH 0FEh
AL 4Eh (ASCII N) Punctuation Levels
return none
note This call selects one of five Punctuation Character Sets that
can be accessed. The fifth level is "Output Punctuation",
which allows all ASCII characters to be sent to the synthesizer
without being filtered or translated into the Enable Reader 4.0
Punctuation Words.
entry AH 0FEh
AL 4Fh (ASCII O) Help Word Levels
return none
note The Help call selects one of four levels of help. By selecting
"No Help" at the start of your program, you can use the other
Help Functions without having them speak their prompts.
entry AH 0FEh
AL 51h (ASCII Q) Quit
return none
note This call will stop the synthesizer from speaking.
entry AH 0FEh
AL 5Ah (ASCII Z) Letter-to-Word Translator
return none
note This call turns the Letter-To-Word Translator on or off.
For a discussion on the TRANSLATOR Function, read
entry AH 0FEh
AL 54h (ASCII T) Upper Case Identification
return none
note This call toggles identification of uppercase letters.
entry AH 0FEh
AL 56h (ASCII V) Video Output
return none
note The Video Output call toggles the output to the synthesizer
from data that is printed on the video screen.
Function 0FFh CED (CJ Dunford's DOS macro and command-line editor)
CED installable commands
entry AH 0FFh
AL 00h Add Installable Command
01h Remove Installable Command
02h Reserved, may be used to test for CED
installation
BL mode byte
bit 0 callable from DOS prompt
1 callable from application
2-7 not used in public domain CED
DS:SI pointer to CR-terminated command name
ES:DI pointer to far routine entry point
return CF set on error
AX 01h invalid function
02h command not found (subfunction 1 only)
08h insufficient memory (subfunction 0 only)
0Eh bad data (subfunction 0 only)
AH 0FFh if CED not installed
note 1) When PCED returns, AX and the flags are changed. Other
registers are preserved, except as noted.
